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PREFACE 


Taligent Tools for AIX is a reference guide to the tools that Taligent engineers use 
in everyday development work on the AIx® platform. Most of these tools were 
developed specifically for building the Taligent Application Environment®. 


This guide has three parts: 


Taligent Tools describes the tools in detail, and provides information about how to 
use them both collectively and individually. 


Test Frameworks covers the test frameworks that you use to test your programs. 


SNiFF+ Guide is a user’s guide to the SNiFF+ development environment. 
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CHAPTER 1 


INTRODUCTION 


Taligent Tools for AIX describes the Taligent development tools and how to use 
them. Advanced Interactive Executive (AIX) This guide assumes that you are 
running the C Shell (csh) which is the standard shell used for the Taligent build 
environment. If you intend to use a different UNIX Shell, refer to the 


documentation appropriate for that shell. 
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CHAPTER 2 


THE BUILD ENVIRONMENT 


The Taligent AIX build environment was designed to allow individual 
contributors to efficiently accomplish their work, to allow full-system (or major 
subsystem) builds—and to accomplish both in a similar fashion. Once you know 
how to do the first, the second is easy. This chapter focuses on how you, the 
individual contributor, use the build environment. 
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ee BUILD TERMINOLOGY 


Taligent uses these terms when describing the build environment: 


« Buzld—run the necessary tools to generate client and executable files in the 
proper order on any project or any project hierarchy. To accomplish this, 
each project (or project hierarchy) must have its own makefile. See 
“Makefiles” on page 9 for more information. 


# Client files— headers and export files. 

# Header files (.h files)—files containing your C++ class definitions. 

# Export files (.e files) —files containing a list of all entry points in your shared 
library. Your clients link against .e files and the runtime system binds the calls 
to your shared library at run time. 


# Binanes—executable programs or applications that use shared libraries 
during execution. 

# Shared hbraries—Class libraries used by multiple programs are usually loaded 
dynamically at runtime. To build a shared library, compile your source files, 
generate your .e file, and link against other .e files. For building 
applications, use MakeSharedLib (see page 30 for more details). 

# Executables—binaries or shared libraries. To build a program or executable, 
compile your source files and link against .e files using MakeSharedApp. Your 
source files must contain a main entry point. (See “MakeSharedApp” on 
page 30 for more details.) 
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THE BUILD PROCESS 


The Taligent Application Environment is a big web of interdependencies. To 
solve these interdependencies, the build process is occurs in four phases that first 
build all client files, and then build all executables. This automated process 
generates both client and executable files. 


Exports all public header The build process makes header files 

files for clients (*.h) by copying them from the project 
into a common directory where other 
projects (clients) can access them 


Compiles all .C files into .o 
files 


Combines all .o, and The build process makes export files 

generates .e files for (*.e) by compiling *.C files, combining 

clients them into one .o (or .a), and then using 
MakeExportList to generate the .e 
file (see “MakeExportList” on page 27) 


Generates all shared 
libraries and executables 


NOTE For Taligent Operating System builds, files currently have different 
extensions than those cited in the illustration: object files are *.ip, libraries are 
*.1ib, and export files are *.client.ip. 


To automate the build process, use makefile descriptions to specify the files to 
build, and use CreateMake to translate the makefile descriptions and to build the 
files. | 


CAUTION The current build tools do not test to see if your component, 
application, or library has the same name as one used by the system. The build 
process will automatically overwrite the Taligent file with yours if you have a 
duplicate name. 
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MAKEFILES 
MAKFFILES 
The makefiles associated with each project are makefile descriptions, not standard 
makefiles. During a build, Makeit calls CreateMake to translate the makefile 
description to a standard-makefile. Makeit then calls make to analyze the 
dependencies of the generated makefiles and update the project. Because 
makefile descriptions are source code, you can check them in to SCM; but, do 
not check in the generated makefiles. Makefile descriptions have filenames in 
the form Project.PinkMake, where Project is the name of the project or directory. 
Type of target, 
eee nena etree te meer eee common types 
Name of the target include Library, 
Makefile TypeOfTarget TargetName { Program, 
description syntax Label: _ Ae ParentObject, and 
iets eS ee Identifies the build topic, typically SubProjectList 
Label: source, Link, or PublicHeaders 


dudbranreterde lotedpercorcrk corer dbadedrebeetbrcrictrterecaibaciedesccopraedeneceeed 


Library 


Program 
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FileList —-——————________—- ——--——~ The files to process 


CreateMake generates different build rules for each type of target. Here are a few 
common target descriptions 
Generates rules to build a shared library. 


Library WidgetLib { Build WidgetLib, also generates Widget.e to allow 


Source: a other Widget.h files to link in. 
: ean Det Ons WidgetLib is built from 
PublicHeaders : ~ Mesa Wes 
Widget... eee ~——- Export Widget.h to allow other projects to use 
Link: - Widget objects 
TestFrameworkLib a 45,03 
ToolboxLib | i ~~ Specifically link with these files 
; 
Generates rules to build an application. 
Program ShowWidget { 
Source: 7 ee 
nee ae ee — Use all system libraries because there 
ShowWidget.C : is no Link label 
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MAKEIT 


ParentObject 


SubProjectList 


syntax 


Generates rules to build and combine the source files. Frequently used to 
combine several projects into one larger library. 


ParentObject FooBarLib { ————-— Generate FoobarLib.o to be ParentObject targets do 


source: | included in the build of another not require a Link label 
Foo.C library because they are not 


publicheaders: 


Foo.h © 
Barch ———— Exported for clients 


A special type of target that lists all the sub projects that you want to build; it does 
not have a target name or any labels. Makeit uses this list when traversing the 
project hierarchy and only builds from those directories listed. 


SubProjectList { 
SubProjl -—-—------------------—._ Build SubProject1 and SubProject2, but ignore SubProject3, 
SubProj2 even though it is part of the project 


Once your have a makefile description, use Makeit to build your project. Makeit is 
a specialized wrapper (or front end) to make. Makeit simplifies builds, provides 
consistency, and has the ability to traverse project hierarchies and convert 
makefile descriptions to real makefiles along the way. 


Makeit [options] [Targets] 


Makeit only has a few options. If you specify any other options, Makeit passes 
them along to make. So in effect, Makeit has the same options as make. For 
information about Makeit and its options, see “Makeit” on page 28. 


If you omit options and targets, Makeit goes through each target in the build _ 
process (Includes, Objects, Exports, and Binaries), and builds the necessary 
dependencies. However, because Makeit is really a wrapper for make, it accepts 
any legitimate target in a makefile. 


Makeit DemoApp 


A common mistake is to build one target (like the previous example), and not 
realize that Makeit is going to do a make on all subprojects of DemoApp—many 
of which do not have a target DemoApp. To prevent Makeit from building 
subprojects, include -c. 


Makeit -c DemoApp 


For more robust examples, see “Real life examples” on page 14. 


TALIGENT TOOLS FOR AIX TALIGENT CONFIDENTIAL: REGISTERED INFORMATION 


PRELIMINARY 


CHAPTER 2 THE BUILD ENVIRONMENT 


MAKEIT 


EEL EEL OL LEE CETL EEL LIL OEP LEE LOLOL EPEC EEP ELE EEE ECE LEE TEER ELE E LE EEE EEE CELE OEE EE LEE ELEC ECOL! 


Passing options 
to make 


Makeit passes any options it does not recognize. You can use this feature to pass 
options to make. Makeit passes arguments to options, and can override variables 
in makefiles. For example, to override the COPTS variable in the makefile: 


Makeit COPTS=-g Binaries 


« The *.Make file does not exist 
« The *.PinkMake file is newer than the *.Make file, or 


# The -M option forced automatic makefile generation. 


Makeit uses CreateMake to translate the makefile descriptions (*.PinkMake) to 
UNIX makefiles (*.Make). 
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Universal. Make 


Other Global Targets 


To prevent duplication in each makefile, and to allow more flexibility, CreateMake 
includes Universal .Make in every generated makefile (*.Make). 


Universal .Make contains global targets and rules. Some of the familiar global 
targets are: Includes, Objects, Exports, and Binaries. Other targets are useful 
because they are applied only to the projects in the build and not to every 
directory in the hierarchy. For example you can have a subsystem that is checked 
into SCM, but is not part of the build. These targets will not be applied to those 
projects. 


Global Target Task 


Clean Remove all .o’s, .e’s, and libraries that were built. 
Complete Expand into the standard targets: Includes, Objects, Exports, and Binaries. 
Makefiles Allows you to traverse the directory and rebuild makefiles as needed. 


The includes, objects, exports, binaries, and clean targets have lower-case 
synonyms, so capitalization is not required. 
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The AIX build environment relies heavily on two types of environment variables: 


Pathname environment variables contain pathnames that are specific to each user. All the 
build tools and makefiles refer to the standard locations through environment 
variables. This allows you to define the location of your working directories. 
$TaligentRoot, set by Setenv, is the basis for all other pathname variables. For 
example, here are two pathnames as set by Setenv: 


The {} bound variable --—-—- setenv TaligentIncludes ${TaligentRoot}/PinkIncludes 
references in shell scripts. setenv TaligentExports ${TaligentRoot}/Exports 

Variable Path to 

LIBPATH Taligent shared libraries used during runtime. 


TaligentBinaries 
TaligentDefaultHomePlace 


TaligentExports 


TaligentExtensionIncludes 
Taligentincludes 
TaligentIncludesDir 


TaligentLibs 
TaligentPlacesRoot 
TaligentRoot 
TaligentSharedLibs 
TaligentSystemDataRoot 


TaligentTemporaries 


TaligentUniversalMake 


Taligent runtime binaries. 


Repository for the current user’s home place (Only one user 
currently for the system.) The Workspace group will provide a 
better object API for getting access to the current user and storage 
areas related to that user in future releases. 


Taligent shared library interface files that developers link with to 
access Taligent shared libraries. 


Directory containing interfaces to system extension developers. 
Main #includes directories used in Taligent builds. 


Base parent directory of all Taligent #inc1udes (this is the parent 
of $Taligentincludes, $TaligentExtensionIncludes, and 
$TaligentObsoletelncludes). 


Directory for certain nonshared libraries. 

Repository where Places for the machine reside. 

The base of everything in the build and runtime system. 
Taligent runtime shared libraries. 


Repository for system data files. These are typically configuration 
files, not first class user data such as movies, images, or sounds. 


Repository for temporary files until people use real Pluto 
temporary file support. 


Universal.Make file used in build system. 
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environment variables 
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environment variables 
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Option environment variables contain the standard options to the standard tools that the Makefile variables 

build uses. Having the options in an environment variable allows you to change are a common 

and experiment with certain options (like debugging options) without alternative to 

disturbing others. Never add options to the compiler (or to any build tools) in environment 

the makefile—use the environment variables instead. variables, but are 

disastrous in our 

Variable Options to build environment. 
CompileOptions x1C command line during builds as the options for building 


Taligent code and default search paths to Taligent #includes. 


MakeSharedAppOptions MakeSharedApp as default options for building a Taligent shared 
library. | 


LinkOptions x1C link command line during builds. 


@NOTE Occasionally a project requires a special option (such as working 
around a compiler bug). For special cases when the project cannot build or will 
not work unless it has a particular option, add the option to the makefile 
description file (*.PinkMake). To add an compiler option, add the following line 
to the *.PinkMake file: 


compileoptions: -NewOptions 


Setenv defines the standard values for all the environment variables that the 
Taligent build environment requires. Always use Setenv to set the variables and 
pathnames. If you need to change a variable, do so after running Setenv. 


The easiest way to change an environment variable is to add to it. For example, in 
a shell script, to add -D__MYDEBUG__ as an option to the compiler: 


setenv CompileOptions "-D__MYDEBUG__ ${CompileOptions}" 


If you frequently add the same option, put the setting in a startup file. 


It is easy to change the environment variables to customize your environment, 
but be careful not to get too carried away with additions. Remember, other 
people need to build your project too; do not become dependent on a particular 
-D you have defined in your environment variable. The system builds use the 
default options as defined in the BuildOptions file. | 
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REAL LIFE EXAMPLES 


By now you should understand the organization of projects and have a 
fundamental grasp of how the build works. This section ties together everything 
you have learned by using several real life examples. | 


A simple sample SimpleSample is similar to Kernighan and Ritchie’s hello world program. This 
program is ideal for demonstrating how to create, build, and execute an 
application. 

How to create | Create a directory named SimpleSample. You can create the directory 


SimpleSample 


anywhere on your file system; in your home directory is probably best. 
Create a source file hel1o.C and enter: 


d#FHinclude <stdio.h> 
void main() 

if | 
printf("Hi there everybody! \n"); 
} 


Use your favorite editor to create hello.C . For custom features that can 
improve Emacs efficiency, see “” on page 97. 


Create a makefile description called Simp]eSample.PinkMake and enter: 


program SimpleSample { 
source: 
hello.C // A single source file 
} 


The name of the *.PinkMake file must be the same as the name of the 
directory in which it resides. The example resides in .../Simp]eSample. 


Build SimpleSample using Makeit without any options or targets (See the 
section Makeit, “Default operation:” on page 22): | 


Makeit 
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The build log 


Makeit messages 


The Includes phase | 


Com MH ov hb 


The Objects phase 


The Exports phase 


The Binaries Phase 


The Copy phase 
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What follows is the build log; yours should look similar. 


The first message is from Makeit stating that it did not find SimpleSample.Make in 
the project. Therefore, Makeit built a makefile from SimpleSample.PinkMake. 
Line 3 is the CreateMake command that Makeit issued to create the makefile. 


HHHE Makeit: No makefile found in ~/home/EeeDee/SimpleSample'. 
THE However one will be built from ~SimpleSample.PinkMake’. 
## CreateMake > SimpleSample.Make; 


Since SimpleSample.PinkMake did not specify any public header files, Makeit did 
not build any include files. 

df 

## Making "Includes" for “/home/EeeDee/SimpleSample"... 


## make -f SimpleSample.Make Includes 
tf 


make: Nothing to be done for ‘Includes'. 


Compiles hello.C to hello.o, and contains the make line that Makeit called. 


# 
4d Making "Objects" for "/home/EeeDee/SimpleSample”... 


4 make -f SimpleSample.Make Objects 


i 
## Compile hello.C to produce hello.o 


Did not build a shared library because SimpleSample did not build an export 
file. 


# 

# Making "Exports" for "/home/EeeDee/SimpleSample”... 
## make -f SimpleSample.Make Exports 

i 


make: ~Exports' is up to date. 


Creates the executable application by calling MakeSharedApp (as echoed from 
make). For more information, see “MakeSharedApp” on page 41 


# 

d## Making "Binaries" for "/home/EeeDee/SimpleSample"... 

#} make -f SimpleSample.Make Binaries 

i 

MakeSharedApp -L. -L/usr/lib/dce -o SimpleSample hello.o /home/EeeDee/work/Expo 
rts/RuntimeLib.e /home/EeeDee/work/Exports/0OpixLib.e /home/EeeDee/work/Exports/T 
oolboxLib.e /home/EeeDee/work/Exports/TimeLib.e /home/EeeDee/work/Exports/TestFr 
ameworkLib.e /home/EeeDee/work/Exports/HighLevelAlbert.e /home/EeeDee/work/Expo 
rts/LowLevelAlbert.e /home/EeeDee/work/Exports/AlbertPixelBuffers.e 


Copies the built application to $TaligentBinaries, the standard location for 
executable files, and leaves a copy in the current directory. 


SmartCopy SimpleSample /home/EeeDee/work/TaligentBinaries 
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How to execute 
SimpleSample 


When the build completes, execute SimpleSample program by typing its name at 
the UNIX prompt. It should look like this: 


% SimpleSample | 
OPIX compile timestamp = Jan 22 1994, 08:25:22 —-——~ The Taligent AIX Layer prints a time-stamp 


Hi there everybody! when it runs an application. 
% 


Fe a a at 


A slightly faster and more efficient way to use Makeit is to include the target 
name. For example, change SimpleSample to use a Taligent object, and then 
rebuild it. 


Change hello.C to look like this: 


#Hinclude <Geometry.h> 


void main() 
{ 
TGRect unUsedRect(0, 1, 2, 4); 
unUsedRect.Print0Object(); // Print coordinates 
} 


Rebuild the application. 


Makeit SimpleSample. 
The build log looks similar to this: 


# 

## Making “SimpleSample" for "/home/EeeDee/SimpleSample"... 

## make -f SimpleSample.Make SimpleSample 

i 

4## Compile hello.C to produce hello.o 

MakeSharedApp -L. -L/usr/lib/dce -o SimpleSample hello.o /home/EeeDee/work/Expo 
rts/RuntimeLib.e /home/EeeDee/work/Exports/0pixLib.e /home/EeeDee/work/Exports/T 
oolboxLib.e /home/EeeDee/work/Exports/TimeLib.e /home/EeeDee/work/Exports/TestFr 
ameworkLib.e /home/EeeDee/work/Exports/HighLevelAlbert.e /home/EeeDee/work/Expo 
rts/LowLevelAlbert.e /home/EeeDee/work/Exports/AlbertPixelBuffers.e 


Running the new SimpleSample should print these results: 


25 impleSample 
OPIX compile timestamp = Jan 22 1994, 08:25:2 


TGRect (top = 1.000000, left = 0.000000, bottom = 4.000000, right = 2.000000) 
v4 
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A clean build To ensure a successful build, delete all the object files before you build a project 
(or project hierarchy). Clean instructs Makeit to delete the object files before 
building the project. 


Makeit Clean Complete 


makefile description for TuffyData (TuffyData.PinkMake) is typical of a Taligent 
application. 


// $Revision: 1.1 $ 
// Copyright (c) 1994 Taligent, Inc. All Rights Reserved. 


Used by all compile —-—-—— compileoption: -D__DEBUG__ -DUSE_FILE_SEGS 
commands. 
Start { 
Copy these make TestHeaderDir=../../AES/UE/Local Includes 
commands into the 
‘ani LocalIncludes :: 
beginning of the 
he test -d $(TestHeaderDir) || mkdir $(TestHeaderDir) 
generated makefile. } 
Directory of headers ————-—— localheaderdir: $(TestHeaderDir) 
to export. 


publicheaders: 
CellModel.h 


| library CellModelLib { 
CellModelView.h 


Pepelasiees a CellSelectionInteractor.h 
makefile commands for | source: 
creating the runtime | CellModel.C 
library. | CellModelView.C 
CellSelections.C 
| CeliModelCommands.C 
CellSelectionInteractor.C 
| link: 
| GraphicDocumentLib 
| StandardDocumentLib 
| NewGraphicApplicationLib 
| BDFTestLib 
| CompoundDocumentLib 
BasicDocumentLib 
NewControlsLib 
| ConstructorArchiveLib 
AlbertScreens 
| {UniversalLinkList} 
i 
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binary CreateTuffyData { 
source: 
— Create make CreateTuffyData.C 


dependencies for link: 


CellModelLib 
Ce ilies StandardDocumentLib 
single executable with 


GraphicDocumentLib 
these sources linked in. NewGraphicApplicationLib 
BDFTestLib 
CompoundDocumentLib 
BasicDocumentLib 
NewControlsLib 
ConstructorArchiveLib 
AlbertScreens 
{UniversalLinkList} 


How do you determine which link files you need to specify in your * .PinkMake 


file? If you don’t specify any link files, CreateMake links all library files. As you can 
imagine, this is not economical. Currently, the only way to determine which link 
files to include is by trial and error, and with a little help from FindSymbols. 


Consider this makefile description called JustAView. PinkMake. JustAView builds a 
shared library and an application binary. To link all library files, create 


JustAView.PinkMake like this: 


Shared library ——-—_ library JustAViewLib { 


| source: | 

| MyView.C 

| 

Main application binary ~~ | binary JustAView { 
source: 


Main.C 
7 } 
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Adding li link libraries 


Add link targets 


Add link targets 


Link tag to add ————_________- 
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To determine which library files to link, include link: targets and specify 
{SimpleLinkList} as the tag in each list. {SimpleLinkList} is a variable specifying 
a minimal set of libraries that most applications require: 


library JustAViewLib { 
source: 
MyView.C 
— |" link: 


{SimpleLinkList} // Minimal set 


binary JustAView { 
source: 
Main.C 


link: 
JustAViewLib 
{SimpleLinkList} 


// The JustAView library created above 
// Minimal set 
} 


Rewwewn 


When you build the JustAView project, Makeit will list errors for undefined 
symbols encountered when MakeSharedLib executes. In the messages, look for 
errors like these below the MakeSharedLib command line: 


. MakeSharedLib -o JustAViewLib ... 


ld: 0711-317 ERROR: Undefined symbol: .TGArea::~TGArea( ) 

1d: 0711-317 ERROR: Undefined symbol: .TRGBColor::~TRGBColor() 
1d: 0711-317 ERROR: Undefined symbol: .TGRect::~TGRect() 

ld: 0711-317 ERROR: Undefined symbol: __vttl2TContentView 


To find the library files in which these symbols are defined, use FindSymbols. 
(The first time you run FindSymbo1s, it parses all library files and builds a 
database file so that subsequent lookups execute quickly.) To perform a lookup, 
run FindSymbols and specify the symbol exactly as it appears in the error listing. 
The symbol name must be enclosed within apostrophes (single quotes). 


FindSymbols '.TGArea::~TGArea()' 


Which produces a listing like this: 


TGArea: :~TGArea(): 
HighLevelAlbert 


This is the unique set of libraries identified: 
HighLevelAlbert 


This listing indicates that the symbol is in HighLevelAlbert. Add thatname as the 
tag in the library’s link: target. To look for multiple symbols at once, include 
each as a separate argument on the FindSymbols command line: 


FindSymbols '.TRGBColor: :~TRGBColor()' '.TGRect::~TGRect()' ' _vttl2TContentView' 
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Which produces this listing: 


TRGBColor::~TRGBColor(): 
LowLevelAlbert 

TGRect: :~TGRect(): 
CommonAlbert 
HighLevelAlbert 
__vtti2TContentView: 
NewGraphicApplicationLib 


This is the unique set of libraries identified: 
CommonAlbert 
HighLevelAlbert 
LowLevelAlbert 
NewGraphicApplicationLib 


Notice that TGRect: :~TGRect(): appears in CommonAlbert and HighLevelAlbert. 
When you get multiple libraries, you probably need to include only one. Try one 
and if you still get errors for the symbol, try the other. In a worst case, include 
both. This example only needed HighLevelAlbert. 


library JustAViewLib { 
source: 
MyView.C 


) link: 
Add link targets ——---------------------[" HighLevelAlbert | // Add 
: LowLevelAlbert // Add 
NewGraphicApplicationLib // Add 
{SimpleLinkList} © 
} 


binary JustAView { 
source: 
Main.C 


link: 


{SimpleLinkList} 
} ; 
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Even if you lookup every symbol in the list, it probably won’t be enough to build 
completely, because the libraries might also require other libraries. When you 
build JustAView again, you get these errors: | 


. MakeSharedLib ... 
1d: 0711-317 ERROR: Undefined symbol: _— vtt5TView 
1d: 0711-317 ERROR: Undefined symbol: .TView: :GetClassMetalInformation( ) 
1d: 0711-317 ERROR: Undefined symbol: .TEventSenderSurrogate: :GetClassMetaInformation( ) 


Repeat the lookup and *.PinkMake modification until MakeSharedLib doesn’t 
return an error. 


Once your build gets past MakeSharedLib without error, you will probably find 
MakeSharedApp producing similar errors: 


. MakeSharedLib ... 
. MakeSharedApp ... 
1d: 0711-317 ERROR: Undefined symbol: TView::virtual-fn-table-ptr-table 
1d: 0711-317 ERROR: Undefined symbol: .TView::GetClassMetalInformation( ) 
1d: 0711-317 ERROR: Undefined symbol: .TEventSenderSurrogate: :GetClassMetaInformation( ) 
1d: 0711-317 ERROR: Undefined symbol: .TInputDevice: :GetClassMetaInformation() 
1d: 0711-317 ERROR: Undefined symbol: .TViewRoot: :~TViewRoot( ) 
Td: 0711-317 ERROR: Undefined symbol: .TViewRoot: : TViewRoot(TRequestProcessor*) 
1d: 0711-317 ERROR: Undefined symbol: .TViewRoot: :AdoptChild(TView*) 


Use FindSymbols again, but this time, add the link: tags to the binary target. 


library JustAViewLib { 


source: 
MyView.C 
link: 
ViewSystemLib 
InputLib 
HighLevelAlbert 
LowLevelAlbert 
NewGraphicApplicationLib 
{SimpleLinkList} 
} 
binary JustAView { 
source: 
Main.C 
link: 
Add link targets —-_-------------- ViewSystemLib 
InputLib 
JustAViewLib 
{SimpleLinkList} 
} 
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Repeat the process until Makeit completes the build. 
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CHAPTER 3 


TLALIGENT BUILD TOOLS 


The Taligent build tools include tools and scripts that you run from the 
command line, and tools and scripts that those tools call. While this chapter 
documents how to run all of the Taligent build tools, there are some tools that 
you should avoid and are so noted. In addition , some tools require you to log on 
with super user access. 
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CREATEMAKE 


Installation 


syntax 


Arguments 


Usage 


Makefile format 


Examples 


CreateMake reads a file Project.PinkMake and creates a UNIX makefile for 
building the project. CreateMake writes the makefile to stdout; by convention, 
you should redirect the output to Project.Make. 


CreateMake is located in /usr/taligent/bin and requires no installation. Make 
sure this directory is in your command search path. 


CreateMake [sourcefile] [-fast] [-D define]... [-I includePath]... 
[-noum] [-vers] > outputfile 


-fast Preprocess the source files and create a single .c that /##includes the source 
files to build each target. this results in faster builds, but is not to be used for 
final builds. 


~| includePath Add the path to the #inc1ude directory search-list. 


—noum Generate a makefile that does not rely on Universal.Make for processing. 
outputtile The file containing the new makefile. If you omit outputfile, output goes to 

/ Stdout. | 

sourcefile The input file to process is usually a *.PinkMake filename. If you omit sourcefile, 


CreateMake assumes the current directory name is the project. For example, if 
the current directory is /TestLib, the sourcefile is TestLib.PinkMake. 


-vers Echo the current version and copyright information to stderr. This is the same 
header that appears at the top of created makefiles. If you use this option with no 
other parameters, the information echoes and CreateMake exits. Otherwise, the 
information echoes and processing continues. | 
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You do not usually call CreateMake directly; instead, you should use Makeit to 
automatically invoke it (see “Makeit” on page 28). Makeit executes CreateMake if 
the makefile is out-of-date or missing. 


CreateMake generates a standard AIX makefile whose content depends on the 
targets in sourcefile. Each makefile supports the standard Taligent build steps 
(Includes, Objects, Exports, and Binaries). 


Simple projects require simple make commands. For example, to create a 
makefile named Sample.Make which builds a target from the C source files in the 
working directory: | 


CreateMake Sample.PinkMake > Sample.Make 
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FindSymbols reports the shared libraries that contain the specified symbols. 


Syntax FindSymbols [ 'symbol' ... ] 


symbol The mangled, demangled, or mixed-form symbol to locate. The argument 
must be enclosed in single quotes (’). | 


Arguments 


Usage Use FindSymbols when MakeSharedLib or MakeSharedApp report unresolved 
symbols, and you want to know which libraries you should add to the link list in 
your *.PinkMake file. 


The first time you run FindSymbols, it builds a cache file: $TaligentExport/ 
_A11Symbols. Subsequent runs consult that cache file. To rebuild or update the 
file, delete it and rerun FindSymbols. When you install a new build, 
InterimInstal1 should delete the cache. 


4@ NOTE If FindSymbols can’t locate a symbol that you are certain exists, the 
symbol is probably an inline. There is no way to find inlines, because they are 
compiled into client code, as opposed to being compiled into and exported from 
a library for use by clients. 


Because the implementation of an inline must be compiled with the header, you 
should be able to find the inline declaration if you do enough searching: it will 
either be hidden down near the bottom of the header, or in another file that is 
an #include in the header (typically similar to “XX XXImplementation.[ih]”). 


A compiler is free to not inline an inline if doing so would generate worse code. 
This means that some symbols declared inline might not actually be inlined, and 
so can wind up compiled into and exported from a library which—if not in the 
* .PinkMake’s link list—would lead to an unresolved symbol error. 


Example You will typically use FindSymbols to locate the library that caused an “Undefined 
symbol” error when your build fails. For example, Makeit might list errors for 
undefined symbols encountered when MakeSharedLib executes. In the messages, 
look for errors like these below the MakeSharedLib command line: 


... MakeSharedLib -o JustAViewLib ... 

ld: 0711-317 ERROR: Undefined symbol: .TGArea::~TGArea() 

ld: 0711-317 ERROR: Undefined symbol: .TRGBColor::~TRGBColor‘( ) 
1d: 0711-317 ERROR: Undefined symbol: .TGRect: :~TGRect( ) 

Id: 0711-317 ERROR: Undefined symbol: __vttl2TContentView 
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FINDSYMBOLS 


Link tag to add to 
your *.PinkMake 


To find the library files in which these symbols are defined, run FindSymbols and 
specify the symbol exactly as it appears in the error listing. The symbol name 
must be enclosed within apostrophes (single quotes). 


FindSymbols '.TGArea::~TGArea()' 


Which produces a listing like this: 


TGArea::~TGArea(): 
HighLevelAlbert 


This is the unique set of libraries identified: 
- HighLevelAlbert 


This listing indicates that the symbol is in HighLevelAlbert. 


To look for multiple symbols at once, include each as a separate argument on the 
FindSymbols command line: 


FindSymbols '.TRGBColor::~TRGBColor()' '.TGRect::~TGRect()' '_ytt12TContentView' 


Which produces this listing: 


TRGBColor::~TRGBColor(): 
LowLevelAlbert 

TGRect::~TGRect(): 
CommonAlbert 
HighLevelAlbert 
__vtti2TContentView: 
NewGraphicApplicationLib 


This is the unique set of libraries identified: 
CommonAl bert 
HighLevelAlbert 
LowLevelAlbert 
NewGraphicApplicationLib 


Notice that TGRect: :~TGRect(): appears in CommonAlbert and HighLevelAlbert. 
When you get multiple libraries, you probably need to include only one. Try one 
and if you still get errors for the symbol, try the other. In a worst case, include 
both. This example only needed HighLevelAlbert. 


It’s also possible to find symbols before using Makeit. To do so, you must take a 
symbol from C++ code and put it into the canonical form used by the linker. This 
isn’t easy. Here are some rules for functions that work 80-90% of the time: 


Remove the return value. 

Preface the function with the ClassName followed by “::”. 
Remove all argument names. 

Remove all whitespace, except: 


© There should be exactly one blank after all const keywords inside a 
function’s argument-parenthesis. 
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@ There should be exactly one blank after a function’s closing ‘)’ and 
before a const keyword. 


For example: 


class TSomeClass { 
int SomeFunc( const TSomeType* someArg, 
TOtherType& otherArg ) const; 
} 


becomes: 

TSomeClass::SomeFunc(const TSomeType*,TOtherType&) const 

Complications creep in when one or more of the types involved are #define’s or 
typedef’s. In such cases, it’s better to choose a different function. 


With practice, you can get good at this technique, and can even find other kinds 
of symbols (enum’s, for example). This may seem like a lot of work, but at least you 
don’t have to keep running the linker. 


This technique is best when you have a program that is already compiled and 
working, and you add some new functionality to it. Then you have a good idea of 
what new symbols you’ve introduced, and what symbols to search for. 
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IPCPurge purges global shared interprocess resources (such as global semaphores 
and shared segments) from memory. Usually IPCPurge is called from mop, which 
is called from StopPink. 


syntax IPCPurge 


CAUTION IPCPurge causes running Taligent applications to end abnormally. 
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MakeExportList generates an .e file from an .o file (which is a combination of one 
or more x1C compiled .C files). Clients of a shared library link with the .e file, 
which is a text list of all the symbols that the shared library provides. 


Usage CreateMake executes this command for you when you are building libraries. You 
should not have to run it independently. 


Example MakeExportList -1 SharedLib MyLib.o > SharedLib.e 
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MAKEIT 


aint 


Installation 


syntax 


Arguments 


Makeit is a wrapper (a front end) to make. Makeit simplifies the builds and 
provides consistency. It has the ability to traverse project hierarchies and convert 
makefile descriptions to real makefiles (by calling CreateMake). 


MakeIt is located in /usr/taligent/bin and requires no installation. Make sure 
this directory is in your command search path if MakelIt fails to run. 


Makeit has only a few options; however, it passes all other options onto make. So in 
effect, Makeit has the same options as make, plus its own options. 


Makeit [options] [Targets] 


Makeit passes any unrecognized arguments on to make. 


—C 


VAR=value 


—Vvers 


Targets 


Do not build subprojects. By default, Makeit operates recursively on 3 


subprojects from the bottom up, executing targets at every project it finds in a 
subproject{} block. 


Do not rebuild a make file, even if it is out of date. 
Do not stop when errors are encountered. This is passed on to make as -i. 
CreateMake option; Makeit passes this option to CreateMake. 


Force all makefiles to be rebuilt on the fly by calling CreateMake even if files 
are up-to-date. 


Traverse the project tree, but do not build anything. 


Assign value to the variable named VAR. Makeit passes this expression to 
make to alter makefile variable usage. 


Echo the current version and copyright information to stderr. 


The targets to build. If you omit this option, Makeit builds each target in the 
current project (Includes, Objects, Exports, and Binaries) and the necessary 
dependencies. You can also specify comp1ete to build the four targets. 


Makefiles is a special targetthat generates a new makefile, but does not build 
anything. Use this for debugging. 


Makeit Makefiles 
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Usage 


Passing options to make 


Creating makefiles 


Universal.Make 
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Go through each build process target (Includes, Objects, Exports, and Binaries) 
and build the necessary dependencies. 


Makeit 
To build DemoApp, and its subprojects: 
Makeit DemoApp 


A common mistake is to tell Makeit to build one target (like the previous 
example), and not realize that it will execute make DemoApp on all subprojects— 
many of which do not have a target DemoApp. To prevent Makeit from building 
subprojects: | 


Makeit -c DemoApp 


To require Makeit to execute only the Includes and Exports targets in each 
directory. 


Makeit Includes Exports 


Makeit accepts (and passes) all options to make. You can use this feature to pass 
options to make. For example if you want make to continue building even if an 
error occurs (-i option for make): 


Makeit -i Objects 


This works similarly for any make option. Makeit is smart enough to pass on any 
arguments for options too. For example, you can override variables in makefiles 
as you can with make. To override the COPTS (compiler options) variable in the 
makefile: | 


Makeit COPTS=-g Binaries 


Makeit can build makefiles on the fly. Makeit rebuilds a makefile if: 
# the *.Make file does not exist 
« the *.PinkMake file is newer than the *.Make file 
” you specify -M to override the automatic makefile generation 


Makeit uses CreateMake to translate the makefile descriptions (*.PinkMake) to 
makefiles (*.Make). 


To prevent duplication in each makefile, and to allow for more flexibility, Makeit 
includes Universal.Make in every makefile (*.Make). Universal.Make contains 
global targets and rules, such as Includes, Objects, Exports, and Binaries. 
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Other global targets In addition to the global targets previously mentioned, other global targets are 
also useful because they are applied only to the projects in the build and not to 
every directory in the hierarchy. For example you might have an entire 
subsystem, that exists, has been checked into SCM, but is not part of the build. 
These targets will not be applied to those projects: 


Global Target Task | 


Clean Removes all .o and .e files, and libraries that were built. 
Capitalization 


es Complete Expands into the four standard targets: Includes, Objects, Exports, 
is optional 


and Binaries. 


Makefiles Allows you to traverse the directory and rebuild makefiles as needed. 


rae et oa “a! PLO P EEL LOLOL EEE LL ELE LETC LE OEE ET LEL EEE LEED ELE CLPL EE ELEL ELEC CEP ELL OPEL LEDC ELE CEL LL EEO EL EERE LELEE CELE ETELL ELE ECOL TELE EEE TELE POL ELE ELE EL ERED LER CELEL ELLE EOE LEE POL EL EEE CELE OLE EEE ELE LLE ELLE LOLOL EERE EL LLL EEE EPAPER OL CLIO 


LLLP LL EEE LEE LEE LLL LILLE EL ELE ELL ELLE LLL EPP LEE LEO EP LLL LE EE LETT OEE EEE TERE E 


MakeSharedApp builds executable applications or programs (it is a wrapper for an 
x1C command with special options). 


Usage CreateMake generates this command for you when you build binaries or 
programs (applications). You should not need to run it independently. 


Example The following example builds the MyApp executable, and specifies two search 
paths -L. (current directory) -L/usr/1ib/dce which will be searched in the order 
specified to load shared libraries SharedLib1 and SharedLib2. If SharedLib1l and 
SharedLib2 are not in these directories, the AIX runtime searches in the path 
specified by LIBPATH. ; 


MakeSharedApp -o MyApp AppMain.o SharedLibl.e SharedLib2.e -L. -L/usr/lib/dce 
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MakeSharedLib is a wrapper to the AIX makeC++SharedLib script, which combines 
.o and .a files into a single shared library, and uses .e files to resolve external 
symbols located in other shared libraries. : 


Usage CreateMake generates this command for you when you are building libraries. You 
| should not have to run it independently. | 


Example To create a shared library named SharedLibI that uses the code in MyLib.o, and 
resolves external symbols by looking in SharedLib2.e: 


MakeSharedLib -p 6000 -o SharedLibl MyLib.o SharedLib2.e 
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syntax 


Arguments 


Usage 


MOP 


syntax 
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MakeSOL registers export-file libraries for Taligent Application Environment. 


MakeSOL [-c | -t | -e pattern | -i pattern | -I files | -E files] [-a file] [-v] 


—a file An additional file to register. 

—C Detects linking against .e files that don’t have corresponding library files. 
—e pattern Excludes files matching the pattern. 

—-E file Excludes the files listed. 

—| pattern Includes files matching the pattern. 

—I file Includes the files listed. 

-t Includes the test libraries. By default, they aren't included. 

-V Lists—to stdout—status messages and the files registered. If you omit this 


option, only warning and error messages appear. 


Use MakeSOL to add new libraries; ones that aren’t already in the build. 


mop is a wrapper for IPCPurge. In addition to calling IPCPurge, it removes 
temporary files created by the AIX implementation of ScreamPlus. You can run 
Mop independently, but it is best to let StartPink or StopPink call it. 


mop 
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RUNDOCUMENT 
RUNDOCUMENT 
Syntax 
Arguments “—¢ Class SharedLib 
—d 
—0 
—p Way 
—s Mode 
DocumentName 
Usage 
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RunDocument creates, opens, or deletes a document that accesses a shared library 
already running in the Taligent Application Environment workspace. 


RunDocument [-c Class SharedLib | -o [-s Mode ] [ -p Way ] | -d ] [ DocumentName ] 


Creates a new document from the TAbstractDocumentStationery subclass 
Class, which is defined in the shared library SharedLib. Can be combined 
with -o to open and create at the same time. — 


If DocumentName already exists, RunDocument appends an integer <n> 
to the name, where <n>is 2 or greater such that the name is unique. 


Deletes DocumentName. 


Opens DocumentName. Can be combined with -c to open and create at 
the same time. 
Specifies the task in which to open the document. Way can be: 
0 = open in same task (default.). 
1 = open in a new task. 
Specifies the mode in which to open the document. Mode can be: 


0 = examine store (default.). 
1 = assume this is a basic document. 
2 = assume this is a compound document. 


The document created, opened, or deleted. If you omit DocumentName, 


use “Untitled” as the default. 


RunDocument prints, to stdout, one of these status codes: 


No error. 


Syntax error in arguments. 
Stationery class not found. 
Document not found. 
Could not delete document. 
Could not open document. 


Could not determine document store type. 


(NOTE In SDKI1, if you are running multiple instances of RunDocument, two 
of them can pick up the same document name. One will successfully create that 
document, but the other will get an exception that causes a SIGIOT. Be sure to use 
a unique name for each instance. 
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SharedLibCache builds a cache of symbol addresses at the end of shared libraries 
for fast subroutine lookup during TStream::Flatten and TStream::Resurrect. 
MakeSharedLib uses SharedLibCache to cache the default constructors of 
MCollectibles for resurrection. 


syntax SharedLibCache [-d sharedLib] [-da sharedLib] [-r sharedLib] 
Arguments —d sharedLib Create cache of symbols required for flatten/resurrect. 
—da sharedLib Create cache of all formal symbols (rarely used). 
—r sharedLib Display the contents of an existing. cache. 
Usage Running strip on a shared library destroys its cache; rerun SharedLibCache to 


rebuild the cache. 


NOTE SharedLibCache is also called sicache. 
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‘SLIBCLEAN 


s1ibclean cleans up global semaphores and global variable space. (Run by 


StopPink.) 
syntax slibclean 
Usage Run s1ibclean between running different versions of Taligent Application 


Environment. The file /etc/s1ibclean should be owned by root and swid. 
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SMARTCOPY 


SmartCopy is a cp imitator that solves one specific problem: during the Includes 
phase of the build, when header files are copied to $TaligentIncludes, if a file 
exists in $TaligentIncludes, and it is write protected, cp fails but SmartCopy does 
not. SmartCopy performs one other important task: it preserves the modification 
date to prevent unnecessary rebuilds. SmartCopy copies a file unless the target file 
has exactly the same date and time, and the same size as the source file. This 
should save you the time of copying the same file over itself, and is more certain 
to copy a file that is truly different. 


Syntax SmartCopy sourceFile.. destFile 
Arguments destFile The destination of the file being copied. 
sourceFile The file(s) to copy. 


STARTPINK 


_StartPink starts the Taligent AIX reference layer and several servers. The 


syntax 


Arguments 


Usage 


remaining servers are started when they are needed (when you launch a Taligent 
Application). | 


StartPink [-a applicationName ] [-q] [-n [-s] ] 


—a applicationName Load and run the named application. 


—n Use merged servers. If you omit this option, StartPink uses non- 
merged servers. 


Merged servers give you a smaller memory footprint, faster start-up, 
and better interactive performance, but less stability. 


-q . Do not load shared libraries. 


—S | Start merged servers as a one. If you omit this option, the merged 
servers start in three groups. -s has no effect if you omit -n. 


When the StartPink script finishes, it displays a message, similar to this: 


Welcome to the Taligent AIX Layer 
Based from v1.0d29 


Copyright (C) 1993, 1994 Taligent, Inc. 
All rights reserved. 
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STOPPINK 
StopPink safely takes down the Taligent AIX layer. StopPink seeks out and kills 
the servers that StartPink started. It also runs mop and slibclean, see “mop” on 
page 31. 

syntax StopPink 

Usage StopPink only kills system servers and applications, not applications that are 


running. Always quit your applications before running StopPink. 


StopPink 
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CHAPTER 4 


CREATEMAKE 


CreateMake generates *.Make files for use with the Taligent build system. This 
chapter describes each of the targets, tags, and options that are available for 
input into CreateMake. For information about using CreateMake, see “Makefiles” 


on page Q. 


NOTE When building for Taligent Application Environment, references ig ee 
compile and link methods are referring to the IBM x1C compiler and linker. 


CreateMake is a Taligent AIX tool that evolved from a similar Macintosh tool 
called CreatePinkMakeFile. CreateMake is faster and can perform more 
operations than its predecessor. Also, CreateMake does not require external tools, 
such as the old MakeMake. CreateMake accepts most of its predecessor’s keywords; 
however, these keywords are not implemented: 


asmoption, dependson, exportclient, exportsample, ISR, makemakeoption, 
opusbugtemplate, otherheaderdir, othersourcedir, plinkclientoption, 
plinklibraryoption, plinkoption, prelude, programdata, and resident. 


PRELIMINARY TALIGENT CONFIDENTIAL: REGISTERED INFORMATION TALIGENT TOOLS FOR AIX 


38 _ CHAPTER 4 CREATEMAKE 
APPLICATION 


Keyword categories There are four categories of CreateMake keywords: 


Targets generate dependencies for a specific output target. All targets contain at 
least one source file declaration with which to build the target. Targets can contain 
various tags, but never other targets. : 


Tags are target specific identifiers for components within that target. Use tags 
within targets to specify, for example, source and header files. 


Variables are keywords used within the generated makefile to control various. 
options. 

Customs are keywords that allow custom control over the generated makefile. 
start and end are examples of custom keywords. 


Path names If a file name contains a slash or starts with a variable, such as $(...), CreateMake 
assumes that you have specified a complete file name. To interpret the name 
literally, enclose the name in single quotes; that is, CreateMake will not prepend a 
directory or append a suffix. 


APPLICATION 


BINARIESSUBFOLDERDIR 


This variable overrides the default destination for binaries built by the makefile 
that CreateMake generates. The default directory is $TaligentBinaries. 


syntax binariessubfolderdir: directoryPath 
Argument directoryPath The path location to copy the built binaries to. This can be an explicit path ora 
shell variable. 

Example binariessubfolderdir: $(TaligentRoot)/MyBinaries: 

library MyLibrary { 

source: 

Library.c 
} 


“@ NOTE For Release A, this keyword is a synonym for subfolderdir, the 
directory identifier used by export{subfolder:}. In later releases, this variable 
will work as described. 
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BINARY 


. This target creates dependencies for a Taligent application, generates all make 
dependencies for creating a Taligent application, and builds an executable/ 
library pair with all sources in the library. 


syntax binary name { 


Argument name The name of the target, and the name used as a prefix for makefile variables, 
include lists, and dependencies. 


An unsupported version of this target is available with the ubinary keyword. 
Unsupported targets are similar to supported targets, except that they are not 
built in the normal build process (Makeit) and require the desired target to be 
explicitly stated for the build to occur. 


Example Produce a makefile for compiling the three source files, link them together with 
standard Taligent libraries, and create a main program binary and a shared 
library containing most of the code. Both of which contain the name “MyApp”: 


binary "MyApp" { 


source: 
main.c 
TMyApp.c 
TMyView.c 
} 


?>NOTE  programis a synonym for binary. 
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This tag is for specifying build rules that control a specific target, from within 
that target. The lines following build must have the correct indentation; they are 
copied directly into the generated makefile. 


Syntax build: 
"$(ObjDir)/Sample.op" : Sample.txt 
$(BuildHelp) Sample.txt -o target 


Example libraryMySample { 
source: 
SampleStartup.c 
SampleIndex.c 


build: | 
$(ObjDir)/Sample.op" : Sample.txt 
$(BuildHelp) Sample.txt -o target 


link: 
Sample.op 
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This variable sets a local variable in the makefile that is used in any compile 
commands executed. 


syntax compileoption: -d option 


Argument option Any option you want to pass on all compile command-lines generated. 


Examples Create a parent object that requires one source file. Pass _WHATEVER_ to the 
compiler when that source file is compiled: 


compileoption: -d _WHATEVER_ 


parentobjects MyObject{ 
source: 
HandleObject.c 


is NOTE cplusoption is a synonym for compileoption that will soon be 
eliminated. Change all occurrences of cplusoption to compileoption. 
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DEVELOPMENTOBJECT 


This target combines the specified source files into a library object, and copies 
the result object file to $TaligentDevelopment. 


syntax developmentobject name { 
j 
Argument name The name of the target. 
Examples developmentobject "SampleObject"™ { 
source: 
SampleInput.c 
SampleQutput.c 
J 


NOTE developmentobject is currently treated the same as object. 


EPL MO BOT PL IDLO A MOB DIDI ISLIP IS EPP IIL IPOD ALLEL IID OL AP EOP L IO IL OD OEP ELILIS IIOP POLLO BANGIN POEMS IAB OPIOID ENABLES IO LEDIOEIY SBOISILOR DYDD DIL MODE DOIPLOILODILEDILLIPLIDIALILISPSPL LLLP IR PEI LSISODSOLISLI SLIPPER OPO PIOLIEIAL GES ELIE LOIS L EDAD GINS IEP IPILISIIAGILIID ADP ILOIOIRIDIL EPIL EL LIED ILIIAPAEPL ELI EPP AOS LMPIIISLEOPEPILEAPLPALILDISLIILIL PEDAL IDOL OOM PL IEMA HO OOO OPO 


PAHOA ARB O ED, 


END 
This custom target allows you to supply a block of make commands to copy into 
the end of the generated makefile. 
syntax end { 
makeCommands 
} 
Argument “makeCommands — Any valid makefile syntax. CreateMake places this block directly into the 
generated makefile; pay careful attention to indentations and syntax. 
Example end { 
Foo : Bar 
## build rules 
} 
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EXPORT 


EXPORT 


Syntax 


Argument 


Example 


A variable that specifies that files in your project be exported to various Taligent 
directories. 


export { 
exportlags — 


exportlags Control which files are exported. Valid tags are: binary, client, 
subfolder, program, data, script, server, library, testlibrary, 
testdata, and script. 


The example shows the destination of each of the supported tags. 


export { 
binary: 

SampleExportBinary // to $(TaligentBinaries) 
client: 

SampleExportClient // to $(TaligentLibraries) 
subfolder: 

SampleExportSubfolder // to $(TaligentBinaries)/subfolder 
program: 

Samp]leExportProgram // to $(TaligentBinaries) 
data: 

SampleExportData 
script: 

SampleExportScript // to $(TaligentSamples) 
server: 
SampleExportServer // to $(OPD)/Servers: 
library: 

SampleExportExportLibrary // to $(0OPD)/SharedLibaries: 
testlibrary: 


SampleExportTestLibrary // to $(OPD)/SharedLibraries: 
TestSharedLibaries: 
testdata: // to $(TaligentTests)TestData: 
SampleExportTestData : 
testscript: // to $(TaligentTests)TestScripts: 


SampleExportTestScript 
} 
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HEADER 
Header files listed after this tag specify an explicit dependency for the target. 
syntax header: 
headerFiles 
Argument headerFiles The header files on which the target is dependent. 
Examples library MyLibrary { 
source: 
LibraryInit.c 
LibraryIQ.c 
header: 
$(CustomHeaders)Library.h 
} 
NOTE In Release A, header acts like publ icheader in that the specified files 
are exported to $TaligentIncludes. header will act as described in future releases. 
HEADERDIR 
This tag specifies an alternate directory in which header files are stored. By 
default, CreateMake generates makefiles with references to headers in the same 
directory as the makefile. CreateMake passes the reference to the compiler. 
syntax headerdir: 
Example headerdir: ../MyHeaders: 
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HEAPSIZE 


syntax 


Argument 


Example 


LIBRARY 


Syntax 


Argument 


Examples 


Syntax 


Argument 


This target controls the allocated heap size of a built Taligent application. 


heapsize: heapSizex 


heapSize The size, in bytes, of the heap. 


binary QECalc { 
source: 
Main.c 
heapsize: 1000000 // 1,000,000 bytes 
} 


This target creates dependencies and makefile commands for creating an library 
to be used in the Taligent runtime system. 


library name { 


} 
name The name of the target. 
library “MyLibrary" { 
source: 
LibraryInit.c 
LibraryI0.c 
} 
This tag specifies all files to link within a target. 
link: 
linkFiles 
linkFiles These files are linked with the listed source files and any other object listed in 


the target. If you omit this tag, nothing is explicitly linked in, and 
$UniversalLinkList is used. 
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LOADDUMP 


syntax 


Argument 


Example 
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This example produces a Taligent program (see “binary” on page 39) by linking 
with the files MenuLib and WindowLib, in that order. 


binary MyProgram { 


source: 
main.c 
Testl.c 
link: 
MenuLib 
WindowLib 
} 
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This target creates build rules for creating a loaddump file with the specified 
headers. All targets built in a *.PinkMake file will have dependencies on the 
specified loaddump file. 


loaddump JoadDumpFilePath { 
} 


loadDumpFilePath The path of the loaddump file. If this file does not exist during the build’s 
Objects phase, the build creates this file. 


NOTE This syntax is not supported when building for Taligent Application 
Environment until the AIX development environment supports loaddump files. 


Create a loaddump file called MyProject.Dump in the directory pointed to by 
$(TaligentRoot)/Dumps: with the given header files included in it. The header 
files must be valid files in $TaligentIncludes or $TaligentPrivateIncludes. 


loaddump "$(TaligentRoot)/Dumps/MyProject.Dump" { 
Application.h 
Test.h 
Format.h 
Dialogs.h 
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LOCAL 


LOCAL 


syntax 


b 


See the description of “localheader.’ 


local: 


LOCALHEADERDIR 


syntax 


Argument 


Example 


This variable specifies the directory in which to export header files for the target. 


localheaderdir: /JocalheaderPath 


localHeaderPath The directory in which to export local headers. if you omit this variable, the 
headers are copied into the same directory as the source files. | 


See the example for “localheader.” 


LOCALHEADER 
This tag specifies header files to export to the localheaderdir header directory. 
Syntax localheader: 
headerFiles 
Argument headerFiles The files to export to the localheaderdir directory. 
Examples Export the file Parents.h into a directory called :LocalHeaders:. If you omit the 
tag localheaderdir, the file is copied to the current directory. 
localheaderdir: ./LocalHeaders: 
parentobject MyParentObj { 
source: 
Parentl.c 
Parent3.c 
Parent5.c 
localheader: 
Parents .h 
} 
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Syntax 


Argument 


Examples 


syntax 


Argument 


Example 
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With this target you can specify you own build rules. Unlike start and end, the 
make target can appear anywhere in the input, and you can have multiple make 
blocks in the input. 


make { 
buildRules 


Foo : Bar 
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This tag specifies a target’s a dependency on object files that might be built 
within another target or project. 


object: 
objectFiles 


objectFiles Link these object files in after any other files produced from specified source 
files within the target. 


Create a dependency for MyLibrary on the file LibI0.c.o0, which is an existing 
object from another target in the same project or another project. The explicit 
path to the object file is not required. 


library MyLibrary { 
source: 
Main.c 
object: 
./ObjectFiles:LibI0O.c.o 
} . 
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OBJECT (TARGET) 


OB SRJECT ee 


syntax 


Argument 


Example 


OBJECTDIR 


Syntax 


Argument 


Example 


This target combines files into a single library object for later use in another 
target or project. 


object name { 


Combine three files into a single library object called MyObject, and Dy it to 
$ObjDir, if it is not the default. 


object MyObject { 


source: 
MySample.c 
MyOtherSample.c 
MyExtraSample.c 
} 


This variable specifies the directory for compile output and link input (object 
files) built within the current project. 


objectdir: path 


path The directory for all compile output and link input. If you omit this variable, the 
build stores these files within the current project in the :ObjectFiles: 
directory. 


Change the directory for built objects to MyObjects, one directory up in the tree. 


objectdir: ../MyObjects: 


@éNOTE In Release A, objectdir does nothing. This will be fixed in a later 
release. . 
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This target is similar to the object target. It combines the specified files into a 
single library object, then it copies the built object into $ParentObjectDir as 
specified by the parentobjectdir variable. 


parentobject name { 


Create MyObject from the compiled output of the three specified files, then copy 
it to the $ParentObjectDir directory. 


parentobject MyObject { 


source: 
MySource.c 
MyMenus.c 
MySample.c 
} 


see 


BA nal 


= NOTE In Release A, parentobject does not export the created object to the 
parent directory. This will be fixed in a later release. 


PARENTOBJECTDIR 


syntax 


Argument 


Examples 


This variable changes the default directory in which to copy objects built from 
the parentobject target. 


parentobjectdir: path 


path The directory for parentobject targets. If you omit this variable, the target 
copies the files to the ObjectFiles directory in the parent directory. 


Use only paths based on the current directory or a known directory tree. Do 
not use a declaration scoped to a specific user volume. 


Change the destination of parentobject copies to the ObjectFiles directory in a 
project called Sample in the parent directory. | 


parentobjetdir: ../Samples/ObjectFiles/ 
CAUTION Do not depend on directories that can change in other projects. In 


example, if the Samples *.PinkMake file ever has a different $ObjDir (set with 
objectdir), this declaration might copy the built object to the wrong place. 
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PRIVATE 
PRIVATE 
Use this tag within a target to specify a dependency on header files located locally 
to the project. 
Syntax - private: 
headerFiles 
Argument headerFiles The local header files for the project. If you omit a header file, the build 
~ searches for the file in the local directory, then in $Taligentincludes, followed 
by $TaligentPrivatelncludes. When you include a header file, the build 
searches in the local directory only. | 
Examples parentobject MyObject { 
source: 
MySource.c , 
MyMenus.c // Look for MyMenus.h locally, then in the other directories 
MySample.c 
private: 
MySource.h // In local directory only 
 MySample.h // In local directory only 
} 
PRIVATEHEADERDIR 
This variable points to a directory to search for header files not in the source 
directory. : 
Syntax privateheaderdir: path 
Argument path | An optional directory for the compiler to search for header files not in the 
source directory. 
Example PrivateHeader.h is not in the current directory. Without the reference to its 


location, compiles cannot locate it if main.c tries to include it. 


privateheaderdir: ../PrivateHeaders: 


library MyLibrary { 
source: 
main.c 
header: 
PrivateHeader.h // not in source directory 
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PUBLIC 


syntax 


Argument 


Examples 


This tag specifies which target headers the public tag can export to 
$TaligentIncludes. 


public: 
headerFiles 


Create a dependency for MyLibrary on the file LibI0. as usual. During the build’s 
Includes phase, export this file to $TaligentIncludes. 


library MyLibrary { 
source: 
main.c 
LibI0O.c 
public: 
LibIO.h 
} 
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SERVER 


SERVER 


syntax 


Argument 


Examples 


SOURCE 


syntax 


Argument 


Examples 


staat 


This target creates dependencies for a Taligent application. All make 
dependencies for creating a Taligent application will be generated for you. This 
target builds a single executable with all sources linked in 


server name { 
} 


name 


An unsupported version of this target is userver. 


Produce a makefile for compiling the three source files, link them together with 
standard Taligent libraries, and create a main program binary and a shared 


library containing most of the code. Both of which contain the name “MyServer”. 


server "MyServer” { 
source: 
main.c 
Server.c 
ServerView.c 


This tag specifies source files within targets. The order of the files in the list is the 
order used to compile, link, and export. 


source: 
targets 


a 


binary “MyApp" { 


source: 
main.c 
TMyApp.c 
TMyView.c 
} 
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SOURCEDIR 
This variable specifies the directory to search for source files. 
syntax sourcedir: path 
Argument path The directory for source files. if you omit this variable, the build searches in 
the same directory as the * . Make file. 
Base this path name on the current directory; do not rely on specific volume 
names or base directory paths—they can change from user to user. 
Examples Change the default location of source files to a directory called Source within the 
current project. 
sourcedir: /Source 
START 
This custom target allows you to supply a block of make commands to copy into 
the beginning of the generated makefile. 
Syntax start { 
makeCommands 
} 
Argument makeCommnds _ Any valid makefile syntax. CreateMake places this block directly in the 
generated makefile; pay careful attention to indentations and syntax. 
Examples start { 
Foo : Bar 
## build rules 
} 
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SUBFOLDER 


syntax 


Argument 


Examples 


SUBFOLDERDIR 


oyntax 


Argument 


Examples 


This tag identifies files within the export target to export to the $SubfolderDir 
within $TaligentBinaries. 


subfolder: 
exportFiles 


exportfiles -—«‘Thefilestoexpot. «= 


Export to the specified files to /MySamp1es/ within the $TaligentBinaries path. 


Subfolderdir: /MySamples 


export { 

subfolder: 
MySamp1eStuff 
MyOtherSamp] eStuff 


This variable specifies the subfolder that is copied to from within an export 
block. 


subfolderdir: directory 


directory The directory to receive export files. 


See example for “subfolder.” 


{NOTE In Release A, binariessubfolder is a synonym that acts the same as 


subfolderdir. In later releases, binariessubfolder will not be a synonym. See the 
“binariessubfolderdir” on page 38 for more information. 
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SUBPROJECT 
This target specifies subprojects to be included when the build system recursively 
builds directories. CreateMake places these subproject names in the 
$SubProjectList variable in * .Make files. 
oyntax subproject { 
subProjects 
} 
Argument ‘subProjects --‘Thesubprojectstobuild. = 
Examples Generate the *.Make file with the three specified subproject/directory names in 
the $SubProjectList, and allow the build system to recursively execute the *.Make 
files in each of these subprojects whenever a make is done on is project. 
subproject { 
FancyText 
FancyDraw 
FancyPrint 
} 
TESTAPPLICATION 
This target is similar to the binary target, but only gets built if “Makeit testing 
complete” is used. See “binary” on page 39 for more information. 
syntax testapplication name { 
d 
TESTLIBRARY 
This target is similar to the library target, but only gets built if “Makeit testing 
complete” is used. See “library” on page 44 for more information. 
Syntax | testlibrary name { 


j 
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Syntax 
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TESTSERVER 


syntax 


ST rs 
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This target is similar to the parentobject target, but only gets built if “Makeit 


testing complete” is used. See “parentobject” on page 49 for more information. 


testparentobject name { 
} 
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This target is similar to the testserver target, but only gets built if “Makeit 
testing complete” is used. See “testserver” on page 56 for more information. 


testserver name { 


This target is similar to the binary target. See “binary” on page 39 for more 
information. _ 


tool name { 
} 
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TRIMDEPENDENCIES 


This target specifies header file paths to remove from the generated makefile. 


syntax trimdependencies { 
headerPaths 
} 
Argument headerPaths The list of header file paths to remove from the generated makefile. If you omit 


these paths, CreateMake includes the list of dependencies found in 
$TaligentIncludes and $TaligentPrivateincludes 


By default, CreateMake includes the list of dependent header files found in 
$TaligentIncludes and $TaligentPrivateincludes. In most cases, these headers do 
not change and the extra dependencies result in larger make files that take 
longer to process. With tr imdependencies, CreateMake removes any dependencies 
found in the list of header files from the generated makefile. 


Examples Strip out any dependencies that begin with $TaligentIncludes or 
$TaligentPrivateIncludes. You can do the same thing with any pathname, 
although generally, you only need to do this with the Taligent public and private 
includes. 


trimdependencies { 
$(TaligentIncludes) 
$(TaligentPrivatelIncludes) 
} 


CAUTION Be careful when using this feature. If a Taligent header used by one of 
your source files changes, that file will not be recompiled. You must manually 
force the file to be recompiled. 
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CHAPTER 5 


ANALYSIS TOOLS 


The heap analysis tools are a set of applications and classes that allow you to 
perform heap-related debugging and dynamic analysis operations. These tools 

are classes that you instantiate and control dynamically, and that use 
TMemoryHook to receive notification of allocations and deletions ina memory . 
heap. 


The heap tools let you: 


# Track block allocation to see who allocated each block (when it is possible to follow 7 
call chains) through several levels of indirection. ek 


# Categorize all heap blocks to determine the type of blocks in the heap (for co | 
example, this block is a TStandardText). | 

# Browse heaps to see all the blocks in the heap, with their size, type, who 
allocated them, who deleted them, and so on. 

# Record memory usage Over time by recording the relative time of each allocation 
and deletion for later analysis. 

« Zap memory by filling uninitialized and deleted blocks with odd byte patterns to 
catch bad pointer usage errors. 

Detect heap corruption by automatically checking the heap for corruption at each 
allocation and deletion. 
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Tradeoffs. 


There are two basic modes of operation: 


: Heap monitoring (the simplest operation) watches the heap at the event 


level and records allocation and deletion events. This produces an ASCII text 
file where each line in the file describes an event. 


# Heap analysis gathers the same data as heap monitoring, but processes the 


events further to produce annotated blocks within a model of the heap. It 
also detects anomalies in heap usage. When it stops watching, the analyzer 
writes a block-by-block description of the heap to an ASCII text file, where 
each line in the file describes a block in the heap. 


Heap Monitoring | Heap Analysis 


Reports each event in the heap. 


Keeps and reports data for blocks currently in _ 
the heap or that were most recently deleted. 


Reports more data, generates a larger data file. | Reports less data, generates a smaller data file. 
Runs slower. | Runs faster. 


Does not detect problems. . Detects problems, such as double deletion. 


To use the local heap tools, modify your code to instantiate a heap tool object— 
either TLocalHeapMonitor or TLocalHeapAnalyzer. Once the object is 
instantiated, monitoring or analysis starts. When you destroy the object (such as 
if it goes out of scope) monitoring or analysis stops. 


Consider a class called TLeaksLikeASieve, which leaks storage when its Leak() 
method is called. The following code starts monitoring, calls the suspect method, 
then automatically stops monitoring when. the monitor object goes out of scope: 


#Finclude <LocalHeapMonitor.h> // for TLocalHeapMonitor 
void main() 


{ 


// Start monitoring; continue until object ‘monitor’ is destroyed. 
TLocalHeapMonitor monitor; 

TLeaksLikeASieve leaker; 

leaker.Leak(); 
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Both the heap monitoring tools and the heap analysis tools are available as 
remote (monitor a different team) or local (monitor the same team).There is no 
separate garbage finding tool. Garbage finding is available as a function of the 
other tools. | 


TLocalHeapMonitor heap monitoring local team 
TLocalHeapAnalyzer heap analysis local team 


TLocalHeapMonitor and TLocalHeapAnalyzer have minimal dependencies. 


The heap tools contain these limitations: 


# The heap analyzer currently keeps data for only the most recently deleted 
heap block. As new blocks come in, old deleted block data is lost. 

# The heap tools consider the heap to be one logical object. In reality, the 
heap consists of two subheaps, the chunky and tree heaps. 


LAPP OLED ELL ILL LODO ELE OLE OOOO IEEE EIEIO A IEEIP EOP EI LED ED LIEBE AEM OO IOP DELL IML ID EID, 


The TLocalHeapMonitor constructor has several options: 


enum EIgnoreOld { kReportOld = 0, kIgnoreOld = 1 }; 
enum EZapMemory { kDontZapMemory = 0, kZapMemory = 1 }; 


TLocalHeapMonitor(const char* outputFileName=0, 
EIgnoreOld ignoreOld=kReportold, 
EZapMemory zapMemory=kDontZapMemory, 
FrameCount depth=8, 
TStandardMemoryHeap* whichHeap=0) ; 


 OutputFileName specifies the name of the output file; the default is "heap_trace’. 


# IgnoreOld, if set to kIgnoreOld, causes all blocks on the heap when monitoring 
was started to be ignored. The default shows all such blocks. 

« ZapMemory, if set to kZapMemory, causes the memory hook to fill blocks with 
recognizable patterns for the purpose of debugging reference-before- 
initialization and reference-after-deletion errors. 


Uninitialized memory gets filled with the pattern OxDEAFBEED. 
Deleted memory gets filled with the pattern 0xFEEDDEAD. 


Depth is the maximum count of functions which the stack crawls will contain. | 
Increasing this option provides more data in some cases, but takes up more 
memory and slows down the tool. 

# WhichHeap specifies which heap to monitor. If unspecified, the default heap is 
monitored. 


ates 
Bs 
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The TLocalHeapAnalyzer constructor has several options: 


enum EIgnoreOld { kReportOld = 0, kIgnoreOld = 1 }; 
enum EOnlyGarbage { kAl1Blocks = 0, kOnlyGarbage = 


a 
enum EZapMemory { kDontZapMemory = 0, kZapMemory 1 } 


TLocalHeapAnalyzer(const char* outputFileName=0, 
EIgnoreOld ignoreOld = kReportold, 
EOnlyGarbage onlyGarbage = kA11Blocks, 
EZapMemory zapMemory = kDontZapMemory, 
FrameCount depth=8, 
TStandardMemoryHeap* whichHeap=0) ; 


« OutputFileName specifies the output file name; the default is "heap_analysis". 


: OnlyGarbage, if set to KOnlyGarbage, causes the analyzer to list only blocks 
which were allocated, but not deleted. The default lists all blocks in the heap. 


All other options are the same as those for TLocalHeapMonitor. 
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In heap monitoring output files, each line describes an event that indicates that: 
# A block was allocated. 
# A block was deleted. 
# A block was already in the heap when monitoring was begun. 
# The heap was corrupted. 


Here is an example of each type of event: 


Thread Time of event Address Size Type Stack crawl 
2-22982 759537687555872 0xb2362718 del TIterator TArrayIterator... 
2-22982 759537687558595 0xb2362950 12 novtb! ~  THybridNumber... 
0-0 old Oxb24020d0 48 TLocal Semaphore 


Thread—the identifier for the thread that called new( ) or delete(). For old blocks, 
this field is 0-0. 


Time of event—the time, in microseconds, of the event. Use this value to determine 
the order of events and to compute the time between events, such as to find the 
age of a block at deletion. For blocks already on the heap when monitoring 
starts, this field is 01d. 


Address—the address of the first byte of the block. 
Size—the size of the block in bytes. If this is a deletion event, the size field is del. 


Type—the type of the block, for blocks that represent C++ objects. If the v-table 
pointer is NIL, this field is novtb1. If the v-table pointer is non-NIL, but it cannot 
be followed to a valid destructor, this field is notype. Note that only deletion 
events and pre-existing block events can have type information. Allocation events 
are always novtb1 because the constructor, if any, has not been called yet. 
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Stack crawi—the function that called new() or delete(). For old blocks, this field is 
empty. The stack crawl consists of several function names, separated by ‘|’ 
characters. The first function name is the innermost. It was called by the next 
function name, and so forth. In the example, the stack crawls have been 
abbreviated. A full stack crawl looks like this: 


TArrayIterator: :~TArrayIterator()|THybridNumerals: :AddFormattingPairAbsolutely(unsigned 
short,long) |THybridNumerals: :AddFormattingPair(unsigned 

short, long) |THybridNumerals::CreateStandardHexNumerals()|TTieredTextBuffer: :NumberFormat 
()|TTieredTextBuffer: :operator<<(const long) |TTieredTextBuffer: :operator<<(const 

int) |TLocalHeapMonitorTest: :ShowMem( void*, long) 
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Heap analysis output files have two sections: the anomaly section and the heap 
dump. In the anomaly section, any anomalies which were detected are described. 
See“Dynamic error detection” on page 65 for explanations of the anomalies that 
can be detected. 


In the heap dump section, each line describes a block in the heap. By default, it 
displays all blocks of the heap. You can also specify to ignore old blocks, or to 
show only undeleted blocks. Use the latter for finding storage leaks. See 
“TLocalHeapAnalyzer” on page 62 for more information. 


Allocation Deletion 
: : : Be 
Address Size Type Age Thread Time Stack Thread Stack 
Oxb0c496b4 1028 TFoo 285198 2-22981 759... TLocal... notask nochain 


Address—the address of the first byte of the block. 
Size—the size of the block. 


Type—the type of the block. If the v-table pointer is NIL, this field is novtb1. If the 
v-table pointer is non-NIL, but it cannot be followed to a valid destructor, this 
field is notype. Note that only deletion events and pre-existing block events can 
have type information. Allocation events are always novtb1 because the 
constructor, if any, has not been called yet. 


Age—the block in microseconds. If the block has been deleted, this is the age of 
the block when it was deleted. 


Allocation thread—the thread that allocated this block. 


Allocation time—the time of the allocation, in microseconds. Use this to determine 
the order in which blocks were allocated. 


Allocation stack crawi—the function that allocated this block. 


Deletion thread—the thread that deleted this block, or notask if the block has not 
been deleted. 


Deletion stack crawi—the function that deleted this block, or nochain if the block has 
not been deleted. 
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Heap corruption 
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corruption 


LAPP LS, PPLE LELAL LOD LIL IL APE L PLE LELEPE LLL L OLLI LILO LL LIPID ILI L IIL L, 


PPP PL LELIOP LIE ODD! POPP LOOP LEED. 


Both the heap analyzer and the heap monitor detect heap corruption by calling 
TMemoryHeap::Check after each allocation event and before each deletion 
event. When the heap is found to be corrupt, the tool writes a message similar to 
the following to the output file and echoes it to the console. In heap monitor 
output files, an asterisk (*) precedes each subsequent line to indicate that the 
corrupt heap. 


KKREKKKEKKEEKEKEREKKRERREKRREKEERREREKR KEK ERK KEERKERRREERRREREEERE 
KkK* 


xxx Tree heap corrupt with error 5. 


x*x*k See PrivateIncludes/TreeHeapExceptions.h for enums. 
K*kk 


KEKEKEKREKEREREREREREEREREKRRERRERRERERKEREKREKREKREREREERERKEEE 


The message states that either the tree heap or the chunky heap is corrupt, and it 
specifies an error number. This number is the return value of the Reason () 
method in the TChunkyHeapCorrupted or TTreeHeapCorrupted exception 
object. To determine its meaning, refer to TreeHeapExceptions.h or 
ChunkyHeapExceptions.h in the PrivateIncludes directory. 


If you have a heap corruption bug, use a heap monitor to debug it. Although the 
heap analyzer also notifies you of heap corruption, it does not help you pinpoint 
the problem. The heap monitor shows the pattern of allocations and deletions 
leading up to the corruption. 


In order to debug the corruption, examine the event before the corruption 
message. If the message that the heap is corrupt occurs before any other events, 
you must start monitoring earlier. Starting with the code indicated by the 
preceding event’s stack crawl, trace forward until you find the corruption. You 
can either read the source code or step in a debugger. The bug will usually 
involve violating array boundaries or misusing pointers. If you see another heap 
event (allocation or deletion), backup; you have gone too far. 


EPPA AP, rane 


On AIX, the heap tools trigger and catch segment violation signals (SIGSEGV) 
during the dynamic typing of blocks. Usually this will be invisible to you. 
However, if you run the heap tools under a debugger, it will trap the signal 
SIGSEGV, and you will enter the debugger that is executing the heap tool code. 
To avoid this, tell the debugger to ignore the signal 11, SIGSEGV. For example, 
in the shell, use : 


xdb -i11 Foo & 
where Foo is your program’s name. Within dbx, use: 


ignore 11 
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DYNAMIC ANALYSIS 


In processing block events, the heap tools analyze incoming data in many ways. 


Dynamic typing The heap tools attempt to determine the type of blocks in the heap (the class 
they instantiate). For raw block events, all allocation events have no type 
information because they represent unconstructed objects. Many blocks cannot 


be typed. 
Dynamic error Dynamic error detection, or desczpline, is the programmatic detection of errors in 
detection either the heap code itself, or calls to the heap indirectly through operators new 


and delete. 
The heap model has several varieties of discipline are built into it: 


Bad address deletion—the detection of addresses that do not correspond to allocated 
blocks in the heap. A subset of this is double deletion detection. Therefore, these 
two anomalies are detected by the same class in an either-or fashion. 


Double deletion detection—the detection of two deletions of the same block. This is 
complicated by the fact that the heap allocates blocks to the same address once 
that address is free. The tool tracks old blocks that have been deleted. When a 
delete of the wrong type or is unmatched by a corresponding new occurs, it is an 
error. 


Non-unique allocate return values—according to the The Annotated C++ Reference Manual 
(by Ellis and Stroustrup), operator new must return unique values (until such 
blocks are deleted). The toll checks this by verifying new allocations against live 
blocks in the existing block map. 


Heap corruption—detected by calling TMemoryHeap::Check at each allocation and 
deletion. | 
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CHAPTER 6 


XCDB 


Xcdb is a graphically oriented symbolic debugger for C, C++, and FORTRAN 


programs running under AIX Version 3, Release 2 (and later). It isa standalone » | 
program, not a windowed front-end to dbx. Xcdb has the breakpointing, stepping, _ 
and traceback capabilities common to most debuggers, but particular attention. _ 


has been paid to presentation and ease of use. Xcdb understands the name 
mangling schemes used by x1C for typesafe linkage. It can display C++ class 
objects, display and set breakpoints in template instantiations, and display the 
internal contents of virtual function tables. 

Xcdb runs under the X11 Release 4 (and later) windowing system and makes full 
use of X capabilities. Since Xcdb runs in a separate X window from the program 
being debugged, each has unrestricted use of the screen, mouse, and keyboard. 
The debugger is mouse driven, meaning that most interactions are performed by 
positioning the mouse over an appropriate screen location and clicking a key or 
button. Xcdb requires little or no typing. 


With Xcdb, you can: 
« Inspect the local environment of any function in the call chain and display 
the format (signed, unsigned, hex, etc.) of any individual variable 


#« Expand aggregate objects (classes, structs, unions, and arrays) to reveal 
arbitrary levels of detail 

# Tailor window layout to your preferences by making appropriate entries in 
your .Xdefaults file 

« Dereference pointers to reveal pointed-to objects 

# Obtain the type, size, and address of any object 

# Call upon C++ class instances to display themselves 
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When Xcdb traps a program interruption, either planned (by setting breakpoints) 
or unplanned (due to program exceptions or external signals), Xcdb makes the 
program state available for inspection. The display includes window panes for: 


z A traceback of uncompleted function calls 
« A view of the source code for the current function, positioned at the current 
line 
# A view of variables defined in the scope of the current function 
« A view of variables defined outside the scope of any function | 
If the program interruption is of a type that allows execution to be continued, 
then you can resume program execution, perhaps after setting or clearing 


breakpoints. You can either ignore the signal that caused the interruption or pass 
it to the program. 


Here is a typical display following a program exception. 


Tocals for Sabet) of stuff c “Callers : Commands Files 


a 
Se 


on 


OO 


i Externals e———__——__4- : 
Se AR AAO AEA AAD i ch AAS 
: An iconized 
window. 
LIED RUE DEOL DART A RY A ROB RII TIS I ATIC SIH IS DDI SLE RNR IR SINR OIE SSID T ONE ERIE Left-click the 
stuf foc mee icon to convert 
it to a normal 
window. 
Left-click the 
title bar to 
convert it to an 


icon. 


ee 
oe 
BS ge 
y 4ay 
is 
a 
re 
Ee 
a 


esate 


cas 


Scenes 


The pointing hand 
icon marks the 
source line 
corresponding to 
the current 
instruction. 
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Locals for subr() of stuff.c : Callers 
esubr 


Activate this menu, 
by left-clicking the “x”. —— 


char. *x; | 


get 
} 


PILL LSS, 


EEX = 225 


pointer 
More detail 
Less detail 
Format as... 


... String 


SE oe array 


..., pointer 
.. address 
...t¥pe 
...8ize 
.. default 


_ Select subrange 
Change value — 


SETUP 
You must be running X11 Release 4 or later, with a graphics display and mouse. 
Use two displays if you will be debugging programs that create virtual hft 
terminals (graPHIGS programs, for example). One display should be used for X 
and the other for the application program. 

Installation Download xcdb6000.tarbin as a binary file, and process it with the tar. For 


example, if you have xcdb6000.tarbin and in /tmp, use the following commands 
to extract the tarfile contents into /usr/bin: 


SU 
cd /usr/bin 


d# become super user 
## go to destination directory 


tar xvf /tmp/xcdb6000.tarbin ## extract contents (Xcdb) 


4 now click Ctri-d to become normal user again 
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RUNNING 


Arguments 


Xcdb lays out its window panes according to a predefined format. The layout is 
scaled to fit the window size specified by your .Xdefaults file, bya command line 
parameter, or by the window manager. “Customization” on page 86 describes 
how you can change the layout (and colors) to your preferences. 


OPEC LTE L LETTE LET EEL EL EEL EOE TELE L TET ELE PLL LEE COLETTE CELLET TE 


To be able to interrupt your program or Xcdb asynchronously from the keyboard, 
define appropriate signal keys using stty. This document assumes that Ctrl-c 
generates an INTR signal and that Ctrl-\ generates a QUIT signal. These are the 
default values on AIX systems. 


make the necessary symbolic information available. Do not use -0 with -g. Xcdb 
cannot reliably debug the resulting program due to code and register motions 
introduced by the compiler’s optimizations. 


xcdb [-geometry WxH+X+Y] 
[-font fontname] 
[-title title] 
[-bw] 
[-wb] 
dirname] 
pid] 
funcname] 
numelts] 
numcalls] 
numdetails] 
numbreaks | 
i signo] 
fetcher] 


aaa aes ee 
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[-p] 


—font fontname The name of a font, overriding the specification in .Xdefaults (if any). 
title title A title to place on the window border. 
—bw Use a black on white color scheme. 
—wb Use a white on black color scheme. 
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—geometry WxH+X+Y A window size and position, overriding the specification in .Xdefaults (if any). 
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-I dirname 


—a pid 
—r funcname 


—e numelts 
—C numcalls 


—d numdetails 


—b numbreaks 


—i signo 


—f fetcher 


—V 


—n 


program 
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A directory to search for source files which cannot be found in the current 
directory (multiple - 1 flags are cumulative; up to 50 directories will be searched 
in the order listed). You can also specify the search path after Xcdb is running: 
see “Preferences” on page 84. 


The ID of an existing process to attach to, instead of starting a new process. 


Specifies how far to run the program’s initialization routines. Normally the 
program runs to the symbol main, the standard starting point for C programs. To 


. Stop at some other function, specify its name. For example, to stop at the 


program's first instruction, specify-r \verb, _, start. 
To stop at the function which initializes C++ static objects, specify 
-r \verb, _,C\verb,_,runtime\verb,_,startup. 


The maximum count of elements to display for any array (default is 1000). 


The maximum count of functions to display in the function call traceback (default 
is 20). 


The count of detail levels to add (or remove) when More( or Less) detail is 
selected from a data object formatting menu. 


The maximum count of breakpoints that can be set simultaneously (default is 50). 


The number of a signal to ignore and pass to the program (multiple -i flags are 
cumulative). 


The name of a program to call when the debugger needs to display a source file 
that it cannot find in the regular unix file system. The debugger invokes the 
program, passes it the name of the desired file as a command line argument, and 
display its output in the Listing window pane. Use this feature if, for example, 
your source files are kept in an SCCS or RCS database. 


Write window layout information to a file named samp1e-1ayout when the 
debugger exits. You can then copy this file into your .Xdefaults file where it 
will be read when you next run the debugger. See “Customization” on page 86. 


Run quietly, only revealing the debugger if the program being debugged stops 
due to a signal or runtime exception. 


Run verbosely, print status information and commentary while running. 


Do not include shared object file symbols when loading the program. For large 
shared libraries, this option can significantly speed up the debugger and reduce 
the amount of virtual memory used. 


Ignore compiler-generated filename qualifiers appearing in the program symbol 
table. This allows source files to be found (by searching the directories specified 
with -1) even if they were moved after the executable was generated. 


The name of the program to execute. 
Arguments to be pass to the program. 
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Program starting 
Program interrupting 
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xcdb -I/u/derek/myproject -e2000 -c20 -i14 -i30 stuff one two three 


invokes Xcdb and: 
# Runs the program stuff with arguments “one two three” 


# Looks for source files in either the current directory or the directory 
/u/derek/myproject 


x Displays up to 2000 elements for any array 
# Displays up to 20 functions in the Callers window pane 


« Ignores signals 14 (SIGALRM) and 30 (SIGUSR1), passing them directly to 
the program without stopping 


POLO LP LARD PLL ELLE LOPS OEP L POI IL LD, 
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To interrupt a running program and return to the debugger, point the mouse to 
the window from which the program was invoked and press Ctrl-c. 


To resume execution, left-click the Run command. 


OR a Oe EL Ee 


To exit the debugger, left-click the Exit command. 


You can also terminate the debugger and executing program by pressing Ctrl-\ 
on the xterm window from which you invoked the debugger. Do this only if both 
the debugger and the program are unresponsive to keyboard input. 


LP LLLPPLILLSLIDLIILD PPL ODL D SOD IPL OD IDEM PISIIPS SRS LIPPIIPPIS. 


The exit code Xcdb returns to the operating system is determined as follows: 


# If the program terminated normally, Xcdb returns the value passed by the 
program to its exit() function. 

# If the program terminated due to an exception, Xcdb returns 255. 

« If Xcdb terminated abnormally, then a value of | is returned. 
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Xcdb has these windows:.: 


Listing 


Locals 


NonLocals 


Callers 


Functions 


Files 


Breakpoints 


Command 


Messages 


Displays the source code for the function selected in the Callers or Functions 
windows, the file selected in the Files window, or a breakpoint selected in the 
Breakpoints window. The window’s title indicates the file’s name. 


Set or clear a breakpoint by clicking on the line to affect. If the source file was used 
to generate code multiple times (as for functions generated from a C++ template 
file or an out of lined inline), a menu prompts you to choose the function instance 
to breakpoint. 


Displays variables defined in the scope of the function selected in the Callers 
window. Click on a value in this window to activates a display- “format menu (see 
“Format Control” on page 76). 


Displays variables defined outside the scope of any function (this includes static 
C++ class members), grouped by translation unit. Click on a value in this window 
to activates a display-format menu (see “Format Control” on page 76). 


Displays a traceback of suspended function activations (most recent at top). Click 
on a function name to display the source code for that function in the Listing 
window and to display its local variables in the Locals window. 


Displays the names of the functions comprising the program. Click on a name to 
display the source code for that function in the Listing window. 


Displays the names of the source files comprising the program. Click on a name to 
display the source code for that function in the Listing window. 


Displays a list of breakpoints currently set. Click on a breakpoint to display the 
source code for that breakpoint in the Listing window. Lines with breakpoints are 
marked with stop sign icons. 


Displays the commands which can be used to control the debugger. Click on 
command to execute it. 


This window pane displays messages from time to time. It is invisible unless there 
is a message to see. 
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INDOW MANIPULATION 


Window and mouse clicks display and control all aspects of the debugger. 


Left button The left button manipulates the contents of a window. To scroll a window, drag the 
contents; the contents scroll in a direction and amount proportional to the 
motion of the mouse. 


Title bar Brings up a menu: 
Move Changes the window’s position 
Resize Changes the window’s size 
Lower Pushes the window down 
Minimize Reduces the window to an icon 
Normalize Restores the window’s original size 
Maximize Enlargse the window to fit the application window 


Horizontal $.B Togglse horizontal scrollbars on or off 

Vertical S.B. Toggles vertical scrollbars on or off 
End of a scroll bar Scrolls the contents one line or column (fast click) or one page (slow click)’. 
Middle of a scroll bar Sets the window to an absolute position on the contents (position is 

proportional to the distance of the mouse from the end of the scrollbar). 


' A fast click is made by pressing and releasing the button in under 1/4 second: anything else is a slow click. 
Right button The right mouse button changes the shape, position, or visibility of a window. 


Center of window | To drag the window to a new position. 


Right-click without moving the mouse pushes the window 
beneath any other windows it might have been obscuring. 


Corner or edge of window To resize the window. 
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KeyS Keys navigate through the window, and execute searches. 
re aoa eee ern Set ran sea cS hand epen atretad te aioli wait a lea a aor at 
Arrow Moves cursor, scrolling the window if necessary. 
Page-up Scrolls window back. 
Page-down scrolls window forward. 
Home Moves cursor to first column of window. 
End Moves cursor to last column of window. 
:nnn Moves cursor to line number nnn (but not past end of file). 
/XXXX search forward to next occurrence of the string XXXX; omit the XXXX to repeat 
search from current position. 
\XXXX Moves cursor backward to preceding occurrence of XXXX; omit the XXXX to 


repeat search from current position. 


Issue commands by left-clicking on an item in the Commands window to bring 


up the Commands menu. 


Line step 
Call step 
Return step 


Signal 


the program with the Restart command. 


Executes the program until a breakpoint is encountered or a signal is received. 


Executes the program until a breakpoint is encountered, a signal is received, or 
control passes to a new line of source code. Executes functions called by the 
current line without stopping. 


Executes the program until a breakpoint is encountered, a signal is received, 
control passes to a new line of source code, or a function call is made.' 


Executes the program until a breakpoint is encountered, a signal is received, or 
control returns to the caller of the current function. 


Resumes execution at the current instruction, passing whatever signal caused the 
interruption back to the program. Any signal sent to the program interrupts 
execution and returns control to the debugger. Signals can arise from: 


A signal key (Ctri-c, for example) clicked in the controlling terminal’s window. You 
probably want the program to ignore the signal and so would resume execution 
with the Run command. 

A signal received in an alarm() or wait() system call. You probably want the program 
to process the signal and so would resume execution with the Signal command. 


A signal generated by a runtime exception. Execution cannot continue, but the 
debugger can still inspect the environment that caused the exception. Re-execute 
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Edit — Invokes an editor on the file in the Listing window. Specifies the editor with 
xcdb. Edit in your .Xdefaults. Use %s and %d symbols for filename and line 
number, respectively. For example, to invoke vi: 


xcdb.Edit: (xterm =+0-0 -n Vi -e vi +%d %s &) 
To invoke emacs: 

xcdb.Edit: (emacs '+%d' '%s' &) 
To invoke v: © 

xcdb. Edit: (v -1 4d 4s &) 


Restart Terminates the program, reloads it, and sets its execution point back to the 
beginning; all breakpoints and data format selections remain unchanged. Ifstdin 
is a file, it is rewound to start-of-file. 


Exit If the debugger was attached to a process using -a, then the process is allowed to 
resume execution (if you want the process to die, you must use kil] -9 from an 
xterm window—there’s no explicit command to do this from Xcdb); otherwise, the 
process terminates and the debugger returns to the operating system. 


Preferences 


' Call stepping into a kernel function is not possible (because there’s no way to set a breakpoint—the text 
segment is read only). Xcdb handles this by running the program until the kernel function returns to the 
point of call. 


A menu prompts adjustments for Xcdb’s behavior. See“Preferences” on page 84. 
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FORMAT CONTROL 


You can reformat objects in the Locals and NonLocals windows in a variety of 
ways, depending on their type. 


Point the cursor to an object’s name or value and left-click to invoke a menu. 
Point the cursor to a menu selection and click again to reformat the object as specified. 


Click outside the menu (or on its title bar) to close the menu without making a change, 
and leave the object’s format unchanged. 
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Default 


Address of 
Type of 
Size of 
oave 
Recall 
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Displays the object’s value in a representation appropriate to its type: 


char A singly quoted letter: ‘a’ 

int A signed integer: -123 

unsigned An unsigned integer: 4294967173 

float A floating point number: 1.23 

enum An enumerator name. 

function A function name. 

class, struct, or A class name (or a member list, see “class, struct, 
union and union formatting” on page 79). 

array The word “array” (or an element list, see “Array 


formatting” on page 80). 


pointer The word “ptr” (or a pointed-to object, see “Pointer 
formatting” on page 83). 


Displays the object’s memory address. 

Displays the object’s type. 

Displays the object’s size. 

Remembers the object’s display format for later reference by Recall. 


Changes the object’s display format to match that of the object most recently 
referenced by Save. 


Edits the object’s value. 


PP LAL LLL LL LOLOL LOLI IO OLED IIL OL PL ALLELE On 


Integer Character Letter format: ‘a’ 
Signed Signed integer format: -123 
Unsigned Unsigned integer format: 4294967173 
Octal Octal format: 0177 
Hex Hex format: 0x7f 
Float “docimal=si“‘(‘é‘sé Ee foratOU!|™€™€~7~™~;7]7} TC=é<i‘ e!#!”!”!”!”CUSCO~C~S*~*~SCS™ 
Scientific “e” format 


Hex 


Hex format: 0x/f 
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Complex 


‘Class, Struct, or Union 


Class 


Array 


Pointer 


Decimal 
Scientific 


Flatten 
More detail 
Less detail 
Show self 


More detail 
Less detail 
String 


Select subrange 


Less detail 
Hex 

String 
Array 


Select subrange 


Cast 


Downcast 


Less detail 


class X { ... 


Real and imaginary parts of the number in “f” format. 

Real and imaginary parts of the number in “e” format.. 

Displays the real and imaginary parts of the number in hex format 
Reveals the members, horizontally. 

Reveals the members, vertically. 

Hides the members. 


Runs the object’s xcdb( ) member function (if any). See “Self-displaying C++ 
objects” on page 85. 


Reveals array elements. 
Hides array elements. 
Displays an array of characters as a null terminated string: “abc”. 


Selects a subrange of the array for display. A prompt asks for the subscripts of the 
elements you wish to see. See“Array formatting” on page 80. 


Hides the pointed-to object. 

The pointer in hex format. 

A pointer to character as a null terminated string. 
At pointer to X as an array of xX. 


A selected subrange of the pointed-to array. A prompt asks for the elements you 
wish to see. 


Changes (casts) the base type of the pointed-to object. A list of struct, union, and 
typedef names prompts to select a new base type. Subsequent formatting of the 
pointed-to objects treats them as if they are of the type you select. 


Converts a C++ pointer to abstract base class into a pointer to most derived class 
by inspecting the pointed-to object’s virtual function table pointer. 


Hides the pointed-to object, for example: 


Ua // base class 


Class Y : public ) i: eee 2 // derived class 
F() { 

X X; 

g(&x); // pass a ‘'pointer-to-X’' 

Y y; 


g(X *p) { 


g(&y); // 
} 


pass a ‘pointer-to-Y' 


// at run time 'p' could be either 
// "pointer-to-X' 
// or "pointer-to-Y' 


// click on 'p* and select "Downcast' 
// to reveal the actual type 
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class, struct, and union Choosing More detail multiple times on a structure reveals increasing levels of 
formatting detail. At the minimum level of detail, only the structure name displays. At the 
maximum level of detail, all of the member names and values display. Similarly, 
clicking Less detail successive times causes the object’s format to fold up. 
Consider the following declaration: 


struct node 
{ 
struct node *next; 
struct data 
{ 
int type; 
float value; 
} data; 
} Node = { 0, { 1, 123 } }; 


This sequence shows how you might inspect the object: 
ClickMore detail here —NOde: node 


Node: { NULL data } 


Click More detail here 


Node: next: NULL 
Click More detail here ——————! data: data 


Node: next: NULL 
ClickMore detail here -—————- data: { 1 123.000000 } 


Node: next: NULL 
data: type: l 
value: 123.000000 


Node: next: NULL 
Click More detail here -———: data: type: 1 


value: 123.000000 


Node: next: NULL 
Click Less detail here ——— Z data: { 1 123.000000 } 


Node: next: NULL 
ClickLess detail here data: data 


Node: { NULL data } 
Click Less detail here ———! 


Node: node 
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You can also examine just a particular field of interest by clicking on that field: 


Node: { NULL data } 
Click More detail here ——————————_________—_—_ 


Node: { NULL { 1 cr eee! } 


Click Type here - 
Node: { NULL { 1 float } } 
Click Hex here 


Node: { NULL { 1 0x42f60000 } } 
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Array formatting Xcdb displays arrays similar to structures, except that the elements are identified 
| by zndices rather than member names. At the minimum level of detail, only the word 
“array” displays. At the maximum level, the indices and values of all the array 
elements display. | 


Statically allocated arrays Consider the following declaration. 


struct point 

{ 

char *name; 

int coord[3]; 

PSA St 

-{"one", {1,1,1}}, 

{"two", {2,2,2}}, 
{"three", {3,3,3}}, 
{"four", {4,4,4}}, 
{"five™, {5,5,5}}, 
{"six", {6,6,6}}, 
Ie 
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This sequence shows how you might inspect the object: 


Set: array 
ClickMore detail here ————~ 
Set: { point point point point ... } 
ClickMore detail here ——--! 
Set: 0: point 
Click More detail here 1: point 
2: point 
3: point 
Set: { ptr array } 


0 
Click More detail here _ eid it ptr array } 
: { ptr array } 


Set: 0: { ptr array } 


ClickMore detail here --——------- Miecisttioe re 


Set: 0: { ptr array } 


3: { ptr array } 
Dynamically allocated In the previous section, the array dimensions were defined at compile time and 
arrays known to the debugger. But for arrays with runtime defined dimensions, the 


debugger has no idea of the outer array dimension, so it assumes a value of 1 
until you tell it otherwise. Consider the following declaration: 


main() 
{ 
char **stuff = malloc(3 * sizeof(char *)); 
stuff[0] = “abc"; 
stuff{1] = "def"; 
stuff[2] = “ghi"; 
return 0; 
} 
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Click String here 


Click Select subrange -- 


here, enter “0,2,...” 


To format stuff as an array of character pointers, step the program until the 


array has been completely initialized, and then: 
stuff: ->->0x6l 


er ee re re ee ee ee eet 


stuff: ->"abc" 


stuff: { "abc" "def" NULL } 


ClickMore detail here ———- 


Subrange selection 


stuff: 0: "abc" 
1: "def" 
22 “ghi"’ 


Select specific subranges of array elements by clicking on the array and choosing 
Select subrange from the menu. Then, type the subscript or range of subscripts 
of the element(s) that you wish to see. Use an expression of the form: 


subrangeSpecifier 


sectionSpecifier 


I 
— 
(o) 

z= 
Zs 
ade 
~s 
~ 


subdimensionSpecifier :: 
| lo '.." **" // all elements 
| terors." hi // all elements 
| '*" tl." '** // all elements 
| a // all elements 
| on // n’th element 


sectionSpecifier { ',' sectionSpecifier }... 


‘LT’ subdimensionSpecifier { '," subdimensionSpecifier }... ‘]’ 


subdim elements between lo and hi, inclusive 


of subdimension, starting at 'lo' 


of subdimension 
of subdimension 
of subdimension 


The count of subdimensionSpecifiers must match the count of array 


dimensions. Here are some examples: 


char array[4][2]; // a4 by 2 array 
[0, *] // matches elements: ~~ [0,0] 
| [0,1] 
Cle e° Wis! vie Ueaks // matches elements: [1,1] 
[2,1] 
[3,0] 
[3,1] 


If a subrange specifier would display more than 1,000 elements, then the 
remainder display as “...”. Change this limit by specifying a different value using 


-e or the xcdb.ArrayLimits item in .Xdefaults. 
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Pointer formatting At the minimum level of detail, only the word “ptr” displays for a pointer object. 
Click More detail to reveal the pointed-to object. Consider the following: 


typedef int (*FUNCP)(); /* a function pointer */ 
FUNCP Table[3] = { main, exit }; /* table of pointers */ 


The sequence below shows how you might inspect the object: 
Table: array 
ClickMore detail here ——— 


Table: { ptr ptr NULL } 
ClickMore detail here ————— } 


ClickMore detail here —_1able: 0: ptr 
1: ptr 
2: NULL 


CHICK TY PO PCG annem 
Table: 0: -> main() 
Ie ptr 
2: NULL 
Click Type here 
Table: 0: -> function-returning-int 
12: (Der 
2: NULL 


Table: 0: pointer-to-function-returning-int 
Click Type here | 1: ptr 


2: NULL 
Table: 3-item-array-of-pointer-to-function-returning-int 
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Set or remove unconditional breakpoints by clicking on the line in the Listing 
window. Set or remove conditional breakpoints that releate to the line indicated 
by the pointing hand icon as follows: 


Run the program to the line where the breakpoint is to be set. 


© Ifyou set a breakpoint to get there, remove it. 


Left-click on an integer or pointer object in the Locals or NonLocals window, 
and select Breakpoint from the menu. 


Enter a breakpoint trigger value for the object, at the prompt. 


Xcdb indicates the breakpoint with a stop sign icon on the source line and with 
an asterisk-marked (*) entry in the Breakpoints window 


Xcdb stops the program whenever the specified line executes, and the object has 
the specified trigger value. 
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PREFERENCES 
PREFERENCES 
To specify your preferences, use the Preferences option from the Commands 
menu in the Commands window. 
Preference settings Language Controls printing of variable names and interpretation of array element addresses. 


Normally, Xcdb determines the language automatically, based on the initial stopping 
point in the program. You can change this by clicking either mouse button to cycle 
through the possibilities: 


C Array element addresses are computed in row major form. 
C++ Array element addresses are computed in row majorform; variable 
names are demangled; nested class members are labeled. 
FORTRAN Array element addresses are computed in column majorform. 
Variables Controls printing of variables in the Locals window pane. 


Lexically scoped _ Displays only the variables in the scope of the current instruction. 


Unscoped Displays all variables in the current function, even those in other 
lexical blocks. This option is a work-around for a bug in some 
compilers—see “Frequently asked questions” on page 88. 


Secret variables Controls visibility of C++ compiler-generated variables. 


Hidden Does not display secret variables. 
Visible Displays secret variables. 
Include Files Controls interpretation of file symbols appearing in the symbol table. 
Respect The debugger makes use of #inc1lude file information appearing 


in the symbol table. 


Ignore The debugger ignores #inc1ude file information appearing in the 
symbol table. This option is a work-around for bugs in cpp, cc, 
and cfront—see “Frequently asked questions” on page 88. 


File search path = Specifies the directories to search when displaying source files in the Listing window. 
Enter a list of directory names, separated by spaces. See also the description of -s. 


Upon fork follow Controls tracing of fork( ) system calls: 
Parent Follows the parent process after a fork() 
Child Follows the child process after a fork() 


When stepping through a fork( ) statement, you must use Line Step and not Call 
Step; otherwise, the debugger gets stuck trying to trace the system call. 


Autoraise Controls automatic raising of interior window upon mouse entry. 


Detail per click Controls the count of levels of detail to reveal (hide) when requesting More detail (Less 
detail) on a structure, union, array, or pointer object. Right-click to increase the value, 
and left-click to decrease it. 
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SELF-DISPLAYING C++ OBJECTS 


This is an experimental feature that allows C++ objects in a program to show 
themselves in response to a request from the debugger. When a C++ object is 
selected on the Locals or NonLocals window, and you choose Show self from the 
menu, Xcdb executes a member function named xcdb(), if found. For every class 
you wish to examine, write an xcdb() member function with these constraints: 


2 no arguments 

# Of type void 

# must not be inline 

# every Class must have its own xcdb() member function (they cannot be 
inherited; they may be virtual, but must be defined for each subclass) 


When you want a class instance to run its xcdb() member function, click on the 
object (as usual), format the object as a “structure” (choose More Detail if you 
only have a pointer to the object), and choose Show self. This runs the object’s 
xcdb() member function. Control then returns to the debugger. 


An xcdb() member function can be written to do anything at all. It might say 
something interesting, display pretty pictures, and so on. Use your imagination. 


Example class Mumble 
{ 
private: const char *name; 
public: Mumble(const char *name) : name(name) {} 
public: const char *name() { return name; } 
public: void xcdb(); 
i 


void Mumble::xcdb() { printf("My name is '%s'.\n", name()); } 


main() 
{ 
Mumble& mumble = *new Mumble("mumble");: 
} 


Clicking on the variable “mumble” in the Locals pane and selecting Show self 
from the menu displays 


My name is ‘mumble’. 


in the xterm window that invoked the debugger. 


Notes Attempting to Show self on aclass or struct for which no xcdb() member 
function is defined produces a complaint, but is otherwise harmless. 


Any breakpoint or exception inside the xcdb() member function, while running 
in the context of Show self, terminates the function (returning control to Xcdb), 
and is otherwise ignored. 
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General 


Layout 


Create layout entries from 
your working environment 
with -1; see “Running” on 
page 70 for information. 


Change Xcdb’s window shape, position, font, colors, and window layouts with 
\$HOME/.Xdefaults. For information about available fonts and colors see /usr/ 
Ipp/X11/defaults/Xfonts and /usr/1ib/X11/rgb.txt, respectively. 


The following tables summarize the .Xdefaults entries. Values to the right of the - 
colon indicate acceptable entries, where: 


geometry is a geometry specification such as “100x300+10-5” 

font is the name of a font, such as “Rom10.500” 

color is the name of a color, such as “Slate Blue” or “#7AD” 

— clothetaen oe 7 oi eae Se ciate cael en ee 
Font: font Font to use for text 
AutoRaise: on |off Behavior of window when mouse enters 
SaveUnder: on |off Handling of pixels obscured by popup menus. On some X servers, 


popup menus run faster with SaveUnder set on; others run faster with 


SaveUnder set off. Try both settings and see which works best for you. 


The layout entries customize each window in the debugger. You must specify settings for all or none of 
the windows; you cannot specify some of the windows. 


SpecialLayout: yes | no Do window specifications follow? 
xxxxGeometry: geometry Size and placement for normal window 
xxxxiconGeometry: geometry Size and placement for iconized window 


xxxxiconifyOk: yes | no Permit iconization of this window? 
xxxxiconStartup: yes | no Iconize window at start-up? 
xxxxscrollbars: vertical | scrollbar style 


horizontal | both | none 


where xxxxis one of Callers, Functions, Files, Breakpoints, Commands, Listing, Locals, NonLocals, 
Formats, or Messages. 


TALIGENT TOOLS FOR AIX TALIGENT CONFIDENTIAL: REGISTERED INFORMATION 


tS 


PRELIMINARY 


Color. 


Xcdb ignores color entries 
on monochrome displays or 
when -bw or -wb has 
been specified. 


Other 


PRELIMINARY 


Borderldle: color 
BorderActive: color 
Foreground: color 
Background: color 
MouseBody: co/or 
MouseOutline: color 
CursorForeground: color 
CursorBackground: color 
MarkForeground: co/or 
MarkBackground: color 
TitleForeground: co/or 
TitleBackground: color 
DialogForeground: color 
DialogBackground: color 
DimForeground: color 
DimBackground: color 
Scrollbuttonidle color 
scrollbuttonActive color 


Editor: command 


Language: /anguage 


RespectincludeFiles: yes | no 


ArrayLimits: NWNN 
DetailPerClick: NNNN 


UnsignedCharFormat: 
decimal | hex 


UnsignedShortFormat 
decimal | hex 
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Window borders, mouse outside 
Window borders, mouse inside 
Normal text 


Normal text 


Mouse body 


Mouse ouiline 

Cursor 

Cursor 

Marked text 

Marked text 

Window pane titles 

Window pane titles 
Command lines 

Command lines 
Non-selectable menu items 
Non-selectable menu items 
scroll buttons, mouse outside 
scroll buttons, mouse inside 


The specified command is invoked when the Edit command is selected 
from the Commands window (see earlier). 


The debugger’s behavior is adjusted for the specified Janguage, as 
described in the Preferences menu section (see earlier). language 
must be one of: 


we C++ 
# FORTRAN 


Controls interpretation of file symbols appearing in the symbol table, 
as described in the {\it Preferences} menu section (see earlier). 


Controls data formatting, as described for the “—e” command line flag 
(see earlier). | 


Controls data formatting, as described for the “-d” command line flag 
(see earlier). 


Selects default data formatting style for unsigned char numbers. 


Selects default data formatting style for unsigned short numbers. 


TALIGENT TOOLS FOR AIX 


87 


88 CHAPTER 6 XCDB 
FREQUENTLY ASKED QUESTIONS 


Example xcdb. Font: Rom17 .500 
xcdb.Background: slate blue 
xcdb. Edit: » (emacs 't%d' '%s' &) 
xcdb.RespectIncludeFiles: yes 
xcdb.ArrayLimits: 2000 
xcdb.DetailPerClick: 2 
xcdb.UnsignedCharFormat: hex 
xcdb.FloatFormat: scientific 
xcdb.AutoRaise: on 
xcdb.SaveUnder: off 


Fi REQUENTLY ASKED QUESTIONS 


Here are the answers to some frequently asked questions. 


Q: This document makes reference to menu item XXXX, but I don’t see it on my 
menu. 


A: Your window pane is either too small or the item has scrolled out of view. Press 
Home and then use the cursor keys to scroll the window contents until you find 
the item you are looking for. 
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Q: A window pane or menu appears to be empty. 


A: See the answer to the previous question. 
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Q: My program runs fine when invoked from the debugger, but doesn’t run when 
invoked from the shell command line. 


A: Unlike the command shell, Xcdb loads your program without searching the 
$PATH environment variable. You’ve probably got a program by the same name 
somewhere in your $PATH. Try explicitly qualifying the program name when you 
type it on the command line. For example, type: 


./test abc ## run program in current directory \end{verbatim} 
instead of: 


test abc # oops, this probably invokes /bin/test \end{verbatim} 
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Q: The debugger stops with a Signal 0 when it encounters the system() function 
in my program. | 


A: This is normal. Just click the Signal item on the command pane to continue, 
or reinvoke Xcdb with “-i 0.” 
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Q: I can’t set a breakpoint on some lines of my C++ program (compiled with 
cfront). 


A: There are bugs in /1ib/cpp, the preprocessor used by cfront to perform 
macro expansion. Try another macro preprocessor—some people have had luck 
with /usr/1pp/X11/Xamples/util/cpp/cpp. Point to it with the CC’s “cppC” 
environment variable, and then recompile. 


There are also bugs in cfront related to generation of #1 ine directives for 
templates and include files. Try setting Include files: Jgnore in the Preferences 
menu and see if this helps. 
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Q: Xcdb displays the wrong source file and/or line number in my C++ program 
(compiled with cfront). 


A: Try setting Include files: Ignore in the Preferences menu and see if this helps. 
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Q: Xcdb displays the wrong source file and/or line number in my C++ program 
(compiled with xlC). 


A: Make sure you have set Include files: Respect in the Preferences menu. Another 
possibility is that the source file contains more than 65,534 lines. Due to an AIX 
symbol table design feature, line information for such files is stored incorrectly. 
The only workaround is to split the source file into smaller pieces. 
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Q: I can’t see one of my local variables, but I know it’s there. 


A: This is due to a compiler bug. Try the Variables: Unscoped option on the 


Preferences menu. 
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Q: My program seems to be running correctly, but the variables displayed by 
Xcdb look wrong. 


A: You probably compiled your program with both -g and -0. The resulting 
compiler optimizations confuse the debugger. Recompile your program with 
either -g or -0, but not both. 
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Q: I can’t see code generated from #include files. 


A: You need a newer version of x1C (such as version 01.02.0000.0000, or later). 


Q: Xcdb complains about an ambiguous breakpoint when I try to set a breakpoint 
on certain parts of my program. 


A: You probably tried to set a breakpoint on an instruction that was one of several 
“instantiations” generated from the same #include file. 


If you are debugging template code generated by the x1C compiler, make sure 
you've set the Language: C++ option on the Preferences menu. 


Otherwise, if you are debugging non-template code, or code generated by 
compilers other than x1C, there is no mechanism by which Xcdb can infer the 
instruction instantiation to which you refer, so it is not possible to set a 
breakpoint on the specified line. Sorry. | 
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Q: I can’t see a traceback in the Callers window pane when I set a breakpoint in a 
signal handler. 


_ A: This is a deficiency in Xcdb that is being addressed. 
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Q: I get an error when attempting to attach the debugger to a process using -a. 


A: This seems to have something to do with shared libraries. If you can reproduce 
this problem with a small program, please send a bug report to the Taligent Tools 
Team. 
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Q: Xcdb is sluggish when stepping. How can I make it faster? 


A: Display update performance during stepping operations can be improved by 
iconifying the NonLocals window pane if it is not needed. The debugger is then 
saved the expense of reading and formatting (potentially large) amounts of 
global data from the program’s execution image. Also, choosing the -n 
command line option will help here, by reducing the number of symbols that 
Xcdb must search. Reducing the size of the main window or using a larger font 
will also help, because it reduces the amount of window drawing that takes place. 
Also, enabling xcdb.SaveUnder in your .Xdefaults file may improve performance 
of pop-up menus (see “Customization” on page 86). 


TALIGENT TOOLS FOR AIX TALIGENT CONFIDENTIAL: REGISTERED INFORMATION 


PPP LLP LEO LEI LIL ID SEP IID L EELS IA IA LON, 


LOLELPILLPLIPL LLL ILL EPL EPELILILI SOD DELI GE LE, 


PRELIMINARY 


PRELIMINARY 


TALIGENT CONFIDENTIAL: REGISTERED INFORMATION 


CHAPTER 6 XCDB 
FREQUENTLY ASKED QUESTIONS 


gl 


PPE Tee Tee Pree Le Tere reer eee rere rere errr eer er errr errr erie errr eee ree rere error ieee reer ee errr er erry ere errr ee rereeee eee rier er eee reer ee rere eee ee er ee eee errr eee e ee eer reer rere eee ree eee ere rere ee eee eee eer eee eee eee eee eevee ee eee reer eee ee reer eee ere rere eet eee ree eee ee rere reese eee eer eee revert eee ere errr rreree eee e rere eer erry eer eerie rere errr reer ee eeereee tere rery 


Q: How can I format a number of variables, all in the same style, without 
tediously clicking more detail on each one? 


A: Try using the Save and Recall selections on the Formats menu to propagate 
the formatting information from one object to all the others. 
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Q: How can I change the display format of all the elements of an array at once, 
without tediously clicking on each one? 


A: Try this: 
Format the first item in the array 
Use Select subrange to (re)select the elements you wish to see 


The format of the first element propagates through to all the other elements 
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Q: How can I invoke Xcdb from inside my program? 
A: Try something like this: 


main() 
{ 
foo(); 
} 


foo() 
{ 
bar(); 
s: 


bar() 


{ 
trouble(): 


} 


trouble() 
{ 
extern char **p_xargv; 
char cmd[100]; 
sprintf(cmd, "xcdb -a 4d %s", getpid(), p_xargv[0]); 


/* undocumented variable */ 


if (fork() == 0) 
system(cmd) ; 
else 
pause(); 


/* runs Xcdb */ 


} 
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Where are the rest? 


A: As a safety feature, Xcdb displays at most 1,000 elements per array. Use -e or 
xcdb.ArrayLimits in your .Xdefaults file to change this limit. 


Q: How can I display a region of memory as an unstructured hex dump? 
A: Try this (ok, it’s a bit of a kludge, but it works): 
Determine the address of the region you wish to inspect (using Format...as 
address, for example) 
Take any convenient char pointer in your program and set its value to the 
address you wish to inspect (using Edit) 
Select the number of elements to be displayed (using Select subrange) — 
Q: What version of Xcdb do I haver 
A: Type xcdb (no arguments) to find out. 
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Q: Where can I get the latest version of Xcdb? 


A: Obtain XCDB6000 PACKAGE from your nearest AIXTOOLS service machine. 
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Q: What’s new in the latest version of Xcdb? 


A: Please read the XCDB6000 NEWS file that is shipped with each XCDB6000 


PACKAGE. 


Q: I have a question that isn’t answered here. 


A: Please report any problems you discover (or wish list items) to the Taligent 


Tools Team. 
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If you encounter a problem with Xcdb, file a Taligent bug report. 
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Trips & TECHNIQUES 


Everybody has their own work style, but there are some simple tricks you cando |... 


to make yourself more productive. Here are some useful pointers. 
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The cdpath shell variable contains a list of directories that shell searches when 
you use cd. For example, if you are in your $HOME directory, you can type: 


cd Envious 


and the shell will take you right there. The shell looks in the current directory 
first, and if it does not find Envious there, it searches the directories in cdpath, 
which is what happens in the previous example. 


This little trick saves a massive amount of typing when you are navigating around 


the Taligent source tree. Here is an example of settings to add to your .cshrc file: 


set cdpath=( ee 
${HOME} \ 
${HOME}/Taligent \ 
${HOME}/tools \ 
${HOME}/Taligent/Toolbox \ 
${HOME}/Taligent/Toolbox/InternationalUtilities \ 
${HOME}/Taligent/Toolbox/Document2 \ 
${HOME}/Taligent/Toolbox/Runtime \ 
${HOME}/Taligent/Albert/Main \ 
${HOME}/Taligent/Instrumentation/TestSystem\ 
${HOME}/Taligent/Time \ 
/home/local \ 
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XCDB— THE DEBUGGER 
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Taligent uses xcdb (an internal IBM project) as its Taligent Application 
Environment debugger. Be sure to read Chapter 6, “Xcdb,” before using this 
debugger. To. make your work with xcdb easier, use the suggested .Xdefaults file 
for standard behavior. 


Instead of calling xcdb directly, use the xdb script which install SCMFetch and turns 
off some interrupts that you probably do not need. 


Within the Taligent Application Environment, OpusBug() is a function that calls a 
UNIX program script which runs a debugger to attach to your running process. 
OpusBug() emulates the functionality of the DebugStr() call found in many 68K 
development environments. While fairly limited because the UNIX environment 
is very different than other development environments, OpusBug() provides the 
rudiments of printing a message and starting a debugger. 


NOTE The origin of the name OpusBug is lost in obscurity. 


When you call OpusBug() within the Taligent Application Environment, it 
# prints a message. 
”@ uses system() to call pink_debugger: the program script. pink_debugger must 
be in your $PATH. 
# then puts your process to sleep for five seconds. This is generally enough 
time for a debugger to get started and attach to the process to be debugged. 
The debugger comes up with sleep() on the top of the stack; below sleep() 


should be OpusBug() and then the routine that called OpusBug(). You should 
be able to debug from there. 


Because OpusBug() invokes pink_debugger via a system() call, it carries a few 
restrictions: 
# The pink_debugger script must terminate with an exit status of zero. 


« The pink_debugger script must not be blocking. This means that anything 
that requires interaction, like a debugger, must be run in the background. 


Here is the prototype for OpusBug(): 


void OpusBug(char *message); // Print the message, and call pink_debugger 


OpusBug() passes two arguments, the process ID and the calling program name, 
to provide enough information for a debugger to attach to a running process. 


Here is a sample pink_debugger. 
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OpusBuG() 


#1 /bin/sh 

+ 

## This program starts an xdb session in the background. 
i 


H 


PROCESS_ID=$1 
__ PROGRAM_NAME=$2 


echo 

echo 

echo "*** Entering pink_debugger ***" 

echo "*** PROCESS ID == $PROCESS ID ***" 
echo "*** PROGRAM _NAME == $PROGRAM_NAME ***" 
taldb -a $PROCESS ID $PROGRAM_NAME & 

echo "*** Exiting pink_debugger ***" 

exit 0 


To print the message, but not start a debugger, pink_debugger should be nothing 
more than exit with a zero return status. 


4 Do not start the debugger 
exit 0 


To neither print a message nor start a debugger ( do nothing), set the 
PINK_DONT_USE_OPUSBUG environment variable. 


setenv PINK_DONT_USE_OPUSBUG 
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CHAPTER 7 


TEST ENVIRONMENT 
OVERVIEW 


The Test environment provides the tools and protocols for developing tests to 
ensure that your code works properly. The Test environment gives you a standard 
way to connect your code to the test conditions and get the test results. 


The Test environment consists of two major elements. 


The Test framework is a collection of classes that provides a standard format for all 
tests and results reporting. The design goal is that anyone can: 


# Run any test 
# Understand the results of any test 
The Test framework also eliminates the need to reinvent solutions to recurring 


problems. For example, the Test framework contains a ready-to-use class to test 
classes derived from MCollectible for proper support of flattening and cloning. 


The Runtest application gives you an execution environment that works with a 
scripting language that allows you to run tests, examine them at run time, and 
retrieve logged outputs after run time. 
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FIGURE 1 
THE TEST 
FRAMEWORK 
PROVIDES A 
CONSISTENT 
INTERFACE 
BETWEEN YOUR 
CODE AND YOUR 
TESTS 


CHAPTER 8 


TEST FRAMEWORK 


The Taligent Operating Environment Test framework provides the structure for _ 


you to link the tests you write to your code. You can then perform any Test- 
framework compliant tests consistently with the RunTest application. 


In addition to performing a test, the Test framework supports: 
« Setup and cleanup operations for each test 
« Different ways to combine tests 
« Test logging and timing 


Your code Your tests 
(target classes) (test classes 


Test F 
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TEST FRAMEWORK OVERVIEW 


The core of the Test framework is the abstract base class TTest. Your test is a 
derived class of TTest or one of its derived classes. 


FIGURE 2 
TEST FRAMEWORK CLASS 
HIERARCHY 
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TTest Class TTest is an abstract base class. Use this class to decide whether a well-defined test 
target works. Create a derived class of TTest for tests that perform a single 
function. TTest contains a Test member function that you must override with the 
code that represents your decision function. A decision function is code you 
write that returns a True or False result when you test a specific condition. 


FIGURE 3 
IMPORTANT 
TIEST 
MEMBER 
FUNCTIONS 


When you declare a derived class of TTest to be a friend of the target class, the 
derived TTest class can access all the private interfaces of the target class for 
internal testing purposes. 


TALIGENT TOOLS FOR AIX TALIGENT CONFIDENTIAL: REGISTERED INFORMATION PRELIMINARY 


Test collection classes 


Protocol tests 


Timing tests 


CHAPTER 8 ‘TEST FRAMEWORK 
TEST FRAMEWORK OVERVIEW 


The Test framework contains derived classes of TTest that allow you to group 
tests that look at different aspects of your code. 


TTestCollection, an abstract base class of TTest, contains a collection of TTest 
instances. The tests in the collection run sequentially to determine the success or 
failure of the entire group. TTestCollection has two concrete derived classes: 


« T’TestSet contains an unordered set of subtests that can be shuffled to vary 
the order the subtests run. 


# ‘T’TestSequence runs its subtests in a fixed sequence. 


TTestMultiplexer derives from Test and supports multiple decision functions 
applied to a single test target. Invoke these decision functions by using text keys. 
You can write a group of decision methods, then build a table that maps keys to 
methods. 


Protocol tests allow you to test an entire tree of classes if those classes are all 
expected to adhere toa protocol. The Test framework contains two protocol 


tests, one for derived classes of MCollectible and another for classes not derived 
from MCollectible. 


TMCollectibleTest tests the implementation of the IsEqual, Hash, Clone, operator>>=, 
and operator<<= members of classes derived from MCollectible. You do not need 
to derive or customize TMCollectibleTest, it is immediately ready for use by 
anyone writing a derived class of MCollectible. 


You can also change or augment TMCollectibleTest to test an enhanced protocol 
superset by overriding some of its members. 


TMCollectibleTypeTest is a derived class of TMCollectibleTest, which is currently 
defined by macros. It tests certain behaviors that cannot be tested without a 
template class including the operator ==, the assignment operator, the copy 
constructor, and the constructor and destructor. . 


TStreamTest is an abstract base class that tests the implementation of operator>>= | 
and operator<<= for classes not derived from MCollectible. Unlike 
TMCollectibleTest, you derive from TStreamTest for each target class you want to 
test. Use the declaration and definition macros supplied with TStreamTest to 
create the required derived classes. 


The TTimingTest base class provides a basic guide for tests that measure the time a 
specific operation takes to complete. TTimingTest contains three framework 
members: TimingSetup, TimingTest, and TimingCleanup. 


Only the TimingTest member function is timed. The TimingSetup and 
TimingCleanup members are run before and after TimingTest but are not timed 
themselves. TTimingTest produces statistical analysis of results. 
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The Test framework uses other classes not directly related to TTest that are useful 
to derived classes of TTest. | 


TTieredText is the class of objects collected by TTieredTextBuffer. It is a derived class 
of T’Text and allows a Test framework user to assign a tier of detail to each 
instance. Tiers are, in increasing level of detail: headline, general, normal, detail, 
and debug. | 


TTieredTextBuffer behaves like the C++ ostream class. It contains <<operators for all 
basic types. Unlike the ostream class, TTieredTextBuffer keeps a collection of all 
text sent to it. Other features of TTieredText are echoing of text to a destination 
you specify, filtering output so that detailed information is suppressed or 
displayed, and flushing text beyond a certain level of detail from the buffer. Each 
instance of TTest contains a TTieredTextBuffer to which derived classes can 
stream diagnostic text messages. TTest itself uses this mechanism to report 
progress and results. 


TTextArgumentDictionary parses a sequence of TText objects into pairs of keys and 
values. This allows you to check quickly for the existence of a keyword on the 
command line or to retrieve the value given for a certain option. 
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Here is an example of how you create a simple test of a member function. 


Assume you have a class named TMySample that has a member function, Add, 
which adds two objects together. You want to know if TMySample::Add works 
correctly. | 


You need to decide the conditions you want to test and what the proper result 
should be. For example, you want to make sure that your Add function properly 
handles integers and complex numbers (a type you have defined). You would 
write a test member that has an operation that adds an integer and a complex 
value and compare that result with the result you expect. If the result is what you 
expect, your test succeeds, otherwise, your test fails. 


The following steps summarize the way you would create a test with the Test 
framework: | 


I Create a new derived class of TTest, TMySampleTestAdd. 


This derived class contains the decision condition for the Add function. 


Verify that an instance of TMySample is available and in the proper state for 
the test. | 


The required TMySample instance is called the target and a pointer to it is 
maintained using TTest::SetTarget and TTest::GetTarget. 


To determine the correct state, you might call Get functions in the target. 
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Override the Setup member function. 


Parse input arguments using TTextArgumentDictionary, if needed, and 
initialize any private data members used for the test. 


If TMySampleTestAdd is part of a TTestCollection, it might share its target 
with the other subtests in the group. 


See “Setting Up the Environment” later in this section. 


Override the Test member function. 


Put the code that determines whether the Add member works correctly here. 
Decide if the test has passed or not and call SetSuccess. 


Example code for test here 


See “Creating a Test” later in this section. 


Override the Cleanup member function 


Perform any cleanup after performing the tests. See “Cleaning Up After a 
Test” later in this section. 


[1 Compile and link into a shared library. 


When you are ready to perform the test, use the RunTest application. 
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A single T’'Test covers an area, large or small, which allows you to determine what 
works and what does not work when the test succeeds or fails. A single TTest can 
exercise a single member function or can parse the input to select a subset of 
member functions. 


You decide how much testing a single TTest derived class needs to perform. Ifa 
single T’lest turns up several defects, the scope of your test is too large. 


The most important part of using the Test framework is designing a test or group 
of tests that properly exercises your code. 


Each of the 
TMyClassTestXX classes 
perform a single operation 


TMyClassTest 
performs 
several 
operations on 
TMyClass 
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Before you use the Test framework to organize your tests, decide what operations 
you can use for each class to test the public, protected, and private interfaces. 


For example, you might find that for a given instance of TMyClass, which 
contains an Add function, you can perform several different operations to test 
that instance. Each operation might take arguments. You might want to have 
several tests of the Add function, passing the test different combinations of 
arguments that the Add function is designed to process, such as reals or vectors. 


Cast each operation as a decision: Does the operation work correctly? The 
outcome of the test condition must be True or False, ere the success of the 
associated test. 


As a special case, when you discover that some sequence of actions causes a 
defect, you need to write a special test that causes that sequence of actions to 
occur in order to implement regression testing. 


ye A TEST 


The minimum requirement to use the Test framework is to include Test.h in your 
source and to link your shared libraries with TestFrameworkLib. 


To use other features of the Test framework, use the following files: 


TestCollection.h 
TestMultiplexer.h 
MCollectible.h 
StartStopTimingTest.h 
StreamTest.h 
TimingTest.h 
MCollectibleTest.h 
TieredTextBuffer.h 
TextArgumentDictionary.h 
TieredText.h 


Your test class and the class you are testing, the target class, have no inheritance 
relationship. Specifically, the test class is not a derived class of the target class. 
Instead, each test class has an instance of its target class. 


Use T’Test::SetTarget and TTest::GetTarget to set and get a pointer to some 
instance that a Test is testing. 
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FIGURE 5 
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The TTest instance that owns the target needs to delete the target when the TTest 
is destroyed. The owning Test must cast the void* target to its correct type, or at 
least the correct base type, before deleting the target, or else the correct 
destructors will not get called. 


You can use a simple naming convention to clarify which test classes relate to the 
classes you are testing. For example, the test class for TMyClass is called 
TMyClassTest. The test class for TMyClass::MyMethod is 
TMyClassMyMethod Test. 


FIGURE 6 MyCode MyTest 
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Writing a test function =§=When you create your test class, you override the Test member function. The Test 
function contains the operations you use to actually perform the test. 


Based on the result of your test operation, your Test function must call 
SetSuccess. Call SetSuccess with True if it passed. Call SetSuccess with False if it 
failed. | 
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MCollectible members 
of TTest 


TTest::Setup performs arbitrary setup in preparation for the Test member 
function. Override Setup to specify any conditions that the test requires. 


Run calls Setup before calling Test. 


If a test is unable to run more than once after the first test runs, have the Setup 
function cause the test to fail on subsequent runs with an appropriate message. 


T’Test::Cleanup is executed even if a software exception occurs. Override 
Cleanup to perform any actions after the test finishes. 


Run catches exceptions that occur in Test and always calls Cleanup after calling 
Test. 


Note that if a hardware exception occurs in Test, such as a bus error, then 
Cleanup is not called. Such a hardware exception will probably kill the thread 
that ran the test but not necessarily the task in which the test was running. 
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To run a test more than once, override TTest::Reset to change the state of the test 
so that you can run the test again. Reset is a public member that any test class can 
call. It is also called automatically inside Run if a test has been run and has not 
been reset. 


To specify the number of times to run the test, use the -n option of the RunTest 
application. 


Derived classes of TTest need to override the streaming operators when member 
variables are added to the class. These new member variables must also be 
streamed for the test to be functional. | 


Override Hash and IsEqual when you want additional derived class information 
to be considered for hashing and equality testing. 
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console 


To write out diagnostic text from a test, use the member function 
OuptutTextStream, which understands the standard C++ operator << for all built- 
in types. Text output produced with this member goes to the console and is also 
saved in a TTieredTextBuffer within the test. You can then log the test, including 
the text buffer. 


If a test fails, you can retrieve the diagnostic text associated with the test to try to 
determine the cause of the failure. 


TTieredTextBuffer sends output to the console. Text that is output in this way is 
saved with the test. This is useful for evaluating the test after resurrecting it from 
a log. However, saving all text to a log can sometimes cause a problem if it uses 
too much memory. 


void TMyClassTest::Test() // This member is in a derived class of TTest 


{ 
OutputTextStream() << “Hello, world\n"; 
} 


To cause some messages to appear on the console but not be saved, use the 
special tier kEphemeral. Note that this is just a special case of the usual tier 
mechanism: 


void TMyClassTest::Test() // This is a derived class of TTest 
{ 
// This will be recorded in the test 
OutputTextStream() << "Important data = " << fData << ‘\n'; 


// Subsequent text will NOT be recorded in the test, to save memory 
OutputTextStream() << PushTier(TTieredtext: :kEphemeral ); 
for (short i=0; 1<32000; ++71) { 

OutputTextStream() << "Loop " << i << ‘\n'; 


} 


// Start recording text again 
OutputTextStream() << PopTier() << "New data = " << fData << ‘\n'; 
} 


You may want to use a TTieredTextBuffer outside of a TTest derived class: 


void TBar::DoStuff(short foo) // This is NOT a derived class of TTest 
{ 

TTieredTextBuffer cout; 

cout << "Foo = " << fo00; 
} 


If you are writing to a TTieredTextBuffer from multiple threads in the same task 
concurrently, you must use a TChunkyTextBuffer. 
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You have three ways to group the tests you have developed: 
« Write a script that performs multiple tests. 
A script allows you to create groups of tests that run sequentially. 
« Combine multiple operations into a single test class. 


This approach allows you to use a single instance that allows you to test 
several functions. Using a single TTest object allows the decision functions to 
share code or member functions. 


Group multiple TTest objects into a single test. 


The approach allows you to run tests in a specific sequence or to run the tests 
in a random order. 


You can combine tests that need to run together as a group into suites. Each test 
suite has a script associated with it that runs all the tests. This script is currently 
an ASCII text file that usually calls RunTest many times. 
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Your TTest class can become very large and complicated if you try to test many 
member functions in the Test member. A simpler way to test multiple member 
functions inside a test class is to create a derived class of TTestMultiplexer. 


TTestMultiplexer contains a number of decision functions. These decision 
functions are methods analogous to the TTest::Test member function. They are 
different in that they return a Boolean result rather than calling 
TTest::SetSucces. A TRUE return value indicates success. Each decision function 
has an associated text key. This key is used to select the decision function at 
runtime. 
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You cannot manipulate the member functions inside a TTestMultiplexer as if 
they were subtests. However, using the TTestMultiplexer derived class allows the 
decision functions to share code or members. 


FIGURE 7 
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To make your tests easier to understand you should name the decision functions 
the same as the member functions. However, there is not always a one-to-one 
correspondence between decision functions and member functions. 


Each decision function decides whether the associated member function in the 
target class works correctly. If some of the member functions in the target class 
are overloaded, you must differentiate the associated decision functions in the 

test class by giving them slightly different names. 


You can use the TTestMultiplexer protocol to run all or some of the test class 
decision functions. 


This means you can write fewer TTest derived classes if you consolidate several 
tests inside a single TTestMultiplexer derived class by placing the behavior of 
each test inside a member function, called a decision function. The decision 
functions can be executed by name using a text input to select the decision 
function to be executed in Test. 
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To make it easier to manage your instances of TTest, use the TTestCollection 
derived classes, TTestSet and TTestSequence, to group related TTest classes into 
a single test. The resulting test passes only if all of its subtests pass. This approach 
allows you to use your TTest classes individually. 


In addition to providing the collection behavior, T'TestCollection derived classes 
allow you to: 

« Define the order subtests execute 

# Shuffle the subtests into new random order 

# Propagate inputs from the group to the subtests 


Every test in a group’s collection is owned by the group. That means when a 
group is destroyed every test in the group’s collection is also destroyed. 
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You can create tests that have different behavior depending on the outcome of 
other tests. For example, TSecondTest only works if the system is in a state that is 
only achieved if TFirstTest is run and passes. 


To allow this, place TFirstTest, then TSecondTest inside a TTestSequence. When 
the T'TestSequence executes, the subtests run in order. If a subtest fails, the 
remaining subtests do not run. This behavior can be switched on and off. 


To ensure that your test has everything it needs to run, check the prerequisites by 
overriding Setup, and if you can’t run a test, then throw an exception in Setup. 
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IDENTIFYING WHAT A TEST DOES 


You can retrieve various types of meta-information, including the purpose of a 
test and the name of the class being tested, using the CopyInfo member function. 


Associated with each test class are meta-information key-value pairs in a 


dictionary. This supports categorization of different kinds of tests and analysis of 
large numbers of test results. 


void TTestTestMultiplexerTest: :CopyInfo(TDictionary& infoDict) const 
{ 
infoDict.AddKeyValuePair(new TStandardText(kDescriptionKey), new TStandardText( 
"A test for the TTestMultiplexer::Test member."™)); 


infoDict.AddKeyValuePair(new TStandardText(kInputSyntaxKey), new TStandardText( 
"TTestTestMultiplexerTest [-p <keyword> | -i <keyword...>]")); 


infoDict.AddKeyValuePair(new TStandardText(kTargetClassKey), new TStandardText( 
"TMultiplexerTest")); 


infoDict.AddKeyValuePair(new TStandardText(kTargetSharedLibraryKey), new 
TStandardText( 


"TestLib™)); 
} 


You can print a test ina textual form in order to browse a collection of tests 
before or after the tests are run. 


PRELIMINARY TALIGENT CONFIDENTIAL: REGISTERED INFORMATION TALIGENT TOOLS FOR AIX 


116 


ION PRELIMINARY 


PRELIMINARY 


CHAPTER Q 


RUN IEST 


One of the primary benefits of the Test environment is a uniform protocol for _ 


running tests. The ability to derive all tests from the abstract base class [Test 


provides this capability. Test framework users need not write applications to run : 


their test—the program RunTest runs all tests derived from TTest. 


Run Test provides the ability to instantiate a derived class of TTest in a newly 
created task, or in another task. — 


When you start RunTest, you must give at least one of the three options -test, -log, _ 


or -start. In addition to these options, RunTest also understands the options of 
TTest::CreateTest. CreateTest options specify what test to run. RunTest options 
specify how the test is to be run. 


You can also create a script that launches RunTest multiple times to group your 
tests into a suite of tests. 
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To perform a test: 


Make sure that your tests are compiled and linked into a shared library. 


Launch the RuntTest application that runs a test, giving the name of the test 
class and the name of the shared library containing that class. 


For example, You can launch RunTest from the console in order to execute a test 
named TMyTest in a shared library named TMySharedLibrary with the following 
command line. The -e d option increases the echoing level to “detail.” 


> RunTest -t TMyTest TMySharedLibrary -e d 


RuntTest passes to your test as arguments any command line arguments following 
the -o option. For example, in order to pass the options called full and 1 to 
TMyTest: 


> RunTest -t TMyTest -1 TMySharedLibrary -ed -o full 1 


You can define the target of a test either in the test class or as a parameter to the 
RunTest program. 


To test class TMyClass, write TMyClassTest, which contains an instance of 
TMyClass as its target. You can attach this instance in your TMyClassTest::Setup 
member function. 


To allow polymorphic testing, use -target option of RunTest. For example, if you 
later make a derived class of TMyClass called TMyClassSubclass, then you can test 
it using TMyClassTest with no recompilation by typing: 


> RunTest -test TMyClassTest MyClassTestLib -target TMyClassSubclass MyClassSubclassLib 
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PROVIDING INPUT FOR A TEST 


Inputs to a test are textual (TText) so you can easily specify them in an 
application and so that a script interpreter can handle them. 


A log contains a test’s original inputs, which allows you to repeat tests with any 
inputs that cause a test to fail. 


Pass input to a test as a collection of TText objects using SetInputs. These TText 
objects must be parsed, much like argv inputs to a main are parsed in an ANSI C 
program. The advantage of this method is that any application can pass inputs to 
a test, and inputs can be accurately logged after a test is run. 


To see what text arguments a test requires, use TTest::CopyInfo to retrieve meta- 
information about a TTest derived class, including the input argument syntax. 


If a test cannot function with a given set of inputs, it can fail with a diagnostic 
about unreasonable inputs. 
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TTextArgument takes as input an ordered collection of TText objects and parses 
the TText objects as arguments on a command line, forming key-value pairs. 


TTextArgumentDictionary is a support class that is not specifically tied to T’lest. 


A leading hyphen character identifies keywords. Anything without a leading 
hyphen is a value argument. Keywords pick up the following argument if it isn’t 
another keyword. For example, the next table shows how the command line 
input to a test is parsed. 


Command line input: 
-foo -bar squal1l8 forkl spoon -ccc 84 85 


Dictionary entries: 


Key Value 
: aa ail 
-bar squall8 
1 fork1 
2 spoon 
-CCC 84 


3 85 oo 
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Note that: 
# All key and value objects are Text objects (actually, a concrete derived class 
of TText). 


# The value associated with -foo is an empty TText, not NIL. This allows clients 
to distinguish “There is no -foo keyword” from “There is a -foo argument 
with no associated value.” 


# The -bar argument picks up the following argument, squall8, as its value. 
« Arguments forkl1, spoon, and 85 have no associated keyword argument and - 


are assigned keys of 1, 2, and 3, in the order in which they appear in the 
input collection. These keys are TTexts not numeric values. 


You can specify that certain keywords never take value arguments. Such keywords 
are called naked options. | 


You can also specify that certain keys can take more than one argument. These 
are called multiple-value options. Another example follows where -x is defined as 
_anaked option and -values and -libs are defined as multiple-value options. 


Command line input: 
-g 40 -x 43 -values 1 4 33 -z 4 -libs Foo Bar 


Dictionary entries: 


Key Value 

-X 

1 43 

-values 1,4, 33 

-Z 4 | 

-libs Foo, Bar . 
Note that: 


# Even though -x is followed by a value, because it is a naked option, it does not 
take the value. Instead, the following value is taken to be a key-less option. 


« The -values and -libs arguments are able to take more than one value, 
because they have been. specified to be multiple-value options. 
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-a(sync] Run test asynchronously, do not wait for test completion. 
This option applies only if -s or -m is given as well. 


When running tests on a server, RunTest normally makes a synchronous call. If you 
specify -a, RunTest instead queues the test on the server and returns immediately. 


-dfebug] RuntTest breaks into the debugger just before calling the TTest::Run member function of 
the test. 
-i[nteractive] By default, tests are not interactive. They do nothing that requires human interaction (no 


dialog boxes, no breaks into the debugger). If you give the -i flag, the test is set to 
interactive mode, and is then able to do user interactions. 


-lo[g] on | off Runfest turns global logging on or off for this machine. This affects all subsequent tests 
that are run with RunTest on this machine for this session, starting with the current test. 

-m{achine] name Runtest runs the test on the named machine. This is functionally similar to specifying -s 
directly on the remote machine. 

-n numberOfRuns The -n option specifies the number of times the test is to be run. 

-o[ptions] Ignores any arguments following -o and passes them to the TTest object by calling 
TTest::Setinputs. 

-S[erver| [name] Run the test within another test server. The server must be specified by the server name. 


If you do not give aname, RunTest uses the named server RemoteTestServer 
communicating through message streams. 


-St[art] RuntTest starts the test server in its own task and remains active indefinitely (normally 
RuntTest terminates immediately after test completion). You must specify the -s option 
with a server name. This server name uniquely identifies the test server. 
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CreateTest options 
interpreted by RunTest Description 


-t[est] class library The TTest derived class to be instantiated and the shared library of the class. CreateTest 
instantiates an object of class class using the default constructor. 


CreateNewObject cannot instantiate the test by name if the derived class has either an in- 
line default constructor or a compiler-supplied default constructor. 


-e[cho] h|g|n|d|D Set detail of diagnostic output: headline, general, normal, detail, Debug. 
This option specifies the echo level for printing the diagnostic output from the tests. 


TTest::OutputTextStream selectively echoes text to the console depending on the echo 
level. 


-ta[rget] class library Specify the class and shared library to be the target of the test. Instantiates an object of 
the class using the empty constructor. Use this option when the test you are running 
requires that the caller setup the target before the Run member function is called. 
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STOPPING A TEST 


To stop a test from inside the test, raise an exception—any exception that you do 
not catch yourself. This is caught by the Test framework and terminates the test. 
This also causes your test to fail, because all tests that terminate by exceptions are 
defined to fail. 7 


To stop a test from outside a test, you must terminate the task running the test. 


TALIGENT TOOLS FOR AIX TALIGENT CONFIDENTIAL: REGISTERED INFORMATION PRELIMINARY 


CHAPTER g RUNTEST 123 
EXAMINING TEST RESULTS 
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PrintTestReport gives you the ability to see the test results for tests that have been 
logged using the -log option in RunTest. PrintTestReport accepts the following 
options on the console command line: 


-e{cho] h|g|n|d|D Set detail of diagnostic output: headline, general, normal, detail, Debug. 
This option specifies the echo level for printing the diagnostic output from the tests. 
-ffail] show failing tests only. By default, prints all tests that have been logged. 
-file fileName Use the log file fileName. 
-k[ey] key [ value] Specify a key and a value to retrieve a more specific subset of the tests. 


For example, you could search the log for all tests with key = kTargetSharedLibraryKey 
and value = HighLevelToolBox, to retrieve all tests run on high level Toolbox. Define the 
key-value pairs for a test in the Copylnfo member function. 


-p[ass] Show passing tests only. By default, prints all the tests that have been logged. 


-s[ummary] Print a summary for all the tests that were logged. The summary includes the total 
number of tests, the number of tests that passed, and the number of tests that failed. 


Collecting timing Tests run for a finite amount of time. You can analyze the total elapsed time to 
information run a test to conduct performance testing. 


You can also identify the times when a test started and stopped to determine if 
tests are running concurrently and might affect each other. 


If a software exception occurs in the Test member function, the Test framework 
catches the exception and handles it. 


To be notified when an exception occurs, override TText::HandleException, 
which is called whenever an exception is caught. 


If a hardware exception or fault occurs in the Test member function, a 
monitoring task can terminate the task running the test. 
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Chapter 11 
Using SNIFF+ ow 


Chapter 12 
Basic Elements 


Chapter 13 
SNIFF+ subsystems 


iS Chapter 14 
oe Customizing your environment 


Chapter 15 
Support for other function: 
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SNiIFF+ GUIDE 


Copyright © 1994 Taligent, Inc. All rights reserved. 
Copyright © 1994 takeFive Software, Inc. All rights reserved. 


This manual is copyrighted. Under the copyright laws, this manual may not be 
copied, in whole or part, without prior written consent of Taligent or takeFive. 


RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the 
government is subject to restrictions as set forth in subparagraph (c) (1) (ii) of 
the Rights in Technical Data and Computer Software clause at DFARS 252.227- 
7013 and FAR 52.227-19. 


This product may be protected by one or more U.S. and International Patents. 


TRADEMARKS: Taligent and the Taligent Design Mark are registered 
trademarks of Taligent, Inc. SNiFF+ is a trademark of takeFive Software, Inc. 
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CHAPTER 10 


GETTING STARTED 


NOTE ‘This documentation is work in progress. 


« The tutorial uses ET++ instead of Taligent examples. 


# Cross-references have not all been updated and the chapters have notbeen _ 
edited. 


# References to the license file do not apply. 


If the SNiFF+ instructions appear to contradict information in earlier parts of the 
Taligent Tools for AIX, follow the information in the earlier chapters. 
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The SNiFF+™ open environment provides browsing, cross-referencing, design 
visualization, documentation, and editing support. It delegates compilation and 
debugging to any C++ compiler and debugger of choice. 
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The SNiFF+ documentation set consists of the following chapters: 
« Getting Started 
Ee Using SNiFF+ 
« Basic Elements 
# SNiFF+ subsystems 
« Customizing your environment 
“Getting Started” and “Using SNiFF+” provide step-by-step introduction to 


SNifFF+. Using a real-world software system, they guide you through the various 
tools and show you how to use them efficiently. 


Both newcomers to C++ or programming environments and experienced 
programmers should read the first two tutorial chapters to learn about the 
underlying principles and provides background information important using 
SNiFF+ tools. 


The remaining reference chapters provide a complete and concise description of 
all SNiFF+ tools and menus. | 


Time needed to work To only read the two tutorial chapters, you will need around 1 1/2 hours. To 

through this manual work through and follow all steps in front of a workstation, you will need roughly 
3 hours. 

Examples used All examples are taken from the ET++ public domain class library, whose source 

throughout this is part of the SNiFF+ software distribution. ET++ is an object-oriented application 

manual framework developed by University of Zirich and the UBILAB of the Union 


Bank of Switzerland. 


Experts know that ET++ is well designed and has a clean object-oriented | 
programming style. The core library without examples has around 250 classes 
and has ca. 80K lines of code. SNiFF+ itself was built on top of an internal version 
of ET++. 


Using ET++ as the basis for this manual allows you to get familiarized with SNiFF+ 
in a context that is very close to real-world software projects. 


Feedback Feedback is always very welcome. Send feedback to our e-mail address: 
| sniff@takeFive.co.at 


Send feedback on class and member descriptions to Taligent. 
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Terminology Before starting the actual description of SNiFF+ it is important to explain the 
meaning of some frequently used terms. 


« While SNiFF+ is a tool, it provides different kinds of tools itself. To simplify 
the text, we use the term tool for all tools SNiFF+ provides. | 

« The exact distinction between the terms editor and browser has been 
blurred so much that they are sometimes used as synonyms. We use the term 
editor (e.g., the Project Editor) when we talk about a tool that is used for 
both viewing and changing data. We call a tool a browser (e.g., the Symbol 
Browser) when it is used for viewing only. All tool names are capitalized. 


/.éNOTE The Documentation Browser can change data when editing is 
engaged (see “Documentation Browser” on page 224). 


« A programming environment deals with source code from which it extracts 
information, which it represents in several ways. This information consists 
mainly of data about declaration, definition, and use of named program 
elements such as classes, methods, variables, and functions. We call a named 
programming language construct a symbol. The repository where SNiFF+ 
stores the information about the symbols defined in a project is called 


symbol table. 
Typographical « Tool names, window names, and menu names start with capital letters. 
conventions Examples: Symbol Browser, File dialog, Icon menu. 


# Menu entries are enclosed in double quotes. 
Example: Menu entry “Mark classes defining method’. 

« Placeholders for names of symbols, selections, or other strings are printed in 
italic. 
Example: Menu entry “Mark classes defining method”. 

# Code examples and inputs that have to be typed in by the user are printed in 
monospace typeface. 
Example: Type in: This text has to be typed in by the user. 

# Special keys are printed in Courier typeface with enclosing '<>'. 
Examples: <Ctrl>, <Enter>, <Alt>. 
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The main goal in developing SNiFF+ was to create an efficient and portable C++ 
programming environment that makes it possible to edit and browse large 
software systems textually and graphically. Much emphasis was placed on run- 
time and memory efficiency and on a comfortable user interface. 


Ww elee anal AOA O CELA ee EC ee Re ONE CMEE IE ANA EERE EER ERECTED CEL ER EEN SERA ER CEE SEEDS 


A running version of SNiFF+ consists of two operating system processes, the 
information extractor and the programming environment itself. The 
information extractor can run locally or on any node on a network. Its task is to 
extract information about definitions and declarations from the source code. 


The programming environment consists of a number of tools that are organized 
around a kernel consisting of the symbol table and the project manager. Both the 
symbol table and the project manager organize information in main storage for 
use by browsers and editors. 


The symbol table manages the information about symbol definitions and 
declarations, and the project manager manages the information about open 
projects, such as the source files they consist of and various attributes. 
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The SNiFF+ information extractor is a fuzzy C++ parser. This means that it 
understands enough about C and C++ to extract the information of interest 
without having to understand C++ completely. This approach makes it possible to 
parse every file only once without including header files and expanding macros. 


Not expanding macros is somewhat controversial because it could result in a loss 
of information if macros are used to change the syntax or semantics of C++. 
Experience with real projects shows that this is not a problem. Not expanding 
macros means that the symbolic information corresponds exactly to the locally 
visible source code. This is frequently an advantage, for example, when macros 
are used to put unique prefixes in front of all class names. | 


The SNiFF+ information extractor extracts information about declarations and 
definitions of C++ language elements and macros. It does not extract 
information about the usage of symbols. This information is extracted on the fly 
with the Retriever. 
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Updating information 
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Project caiicant 


Symbol Browser 


Class Browser 


Hierarchy Browser 
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If the source code of a project is edited, the information about the location of the 
affected symbols is updated immediately. On saving a file, its symbolic 
information is extracted anew and all browsing tools are updated. A user, 
therefore, always works with symbol-based tools presenting information that 
correctly mirrors the source code without ever having to bother about the effects 
of changes. This updating is done only if the SNiFF+ Editor is used 


‘-@ NOTE If the source files are changed with external editors (e.g., vi), SNiFF+'s 
symbol table is updated next time the file is read. 
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To start working with SNiFF+, a developer has to define a project. A project 
consists of a set of source files and, possibly, a set of subprojects that can be 
shared among projects. A subproject is a complete project on its own. 


A typical project structure for a program building on a class library is to have a 
root project containing the project-specific (application-specific) source files and 
to load the library project as a subproject. Library projects are frequently trees of 
projects themselves. 


Whenever a project is opened or a file or a subproject is loaded into the current 
project, its source code is analyzed and the information about the symbols 
defined therein is stored in the SNiFF+ symbol table. 


/@ NOTE Software systems (like InterViews) that store implementation and 
header files in different directories can be handled best with SNiFF+ by creating 
separate projects for the implementation files and for the header files. The 
Implementation file project is then loaded into the header file project as a 
subproject. 
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Browsers and editors. Once a new project is defined with the Project Editor or an existing project is 


opened, it can be browsed and edited in different ways. 
The Symbol Browser provides an overview of symbols defined in the source code; 
it displays the results of queries sent from other tools (e.g., “list all symbols 


matching a certain name”). 


The Class Browser can be used to browse through the locally defined and 
inherited elements of a class. 


The Hierarchy Browser displays the inheritance hierarchy and visualizes queries 
such as “mark all classes declaring method Add()”. 
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Retriever 


Editor 


Documentation Browser 


The Retriever can be used to obtain information about where a certain symbol is 
used in the source code (i.e., cross-reference information). The Retriever is a 
text-search-based tool. It makes it possible to extract all occurrences of strings 
matching the name of a symbol (or any regular expression) in a set of projects 
and to apply semantic filters to the matches. 


SNiFF+ has two possibilities for editing: 


« The integrated Editor is a mouse- and menu-driven Editor. It understands 

~ C/C++ syntax, provides browsing support, and automatically highlights 
structurally important information such as class names, method names, and 
comments. When a source file is modified, it is possible to trigger its 
compilation from the Editor and to mark the source lines where the 
compiler found syntax errors. 


# ‘The Emacs 19 editor has symbol highlighting. This manual uses the 
integrated Editor for all examples. Please refer to “Emacs integration” on 
page 250 for a description of how to integrate Emacs. 


The Documentation Browser lets you view and edit class and member ~ 
descriptions. 
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The complete functionality of SNiFF+ is provided in the menus of the various 
tools. To speed up the work, especially for experienced users, SNiFF+ provides 
three different types of shortcuts to allow faster access to the commands found in 
menus. 


# Keyboard shortcuts are issued by holding down <Alt> of your keyboard and 
pressing the key that is shown at the right of a menu entry. Throughout this 
manual we work with the menus rather than keyboard shortcuts for 
command selection. Some frequently used shortcuts are: 

« <Alt>C for copy 
« <Alt>V for paste 
« <AIt>B for browse class 


# Mouse shortcuts are issued by double-clicking with the mouse on entries in 
lists or selectable items. Throughout this manual mouse shortcuts are used 
wherever possible. Some frequently used shortcuts are: 
# Editing the source of a symbol by double-clicking on it in the Symbol 
Browser 
# Jumping to the source location of a variable by double-clicking on it in 
the Class Browser 
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# Deep clicks are issued by holding down the <Ctrl> key and pressing the left 
mouse button. Some frequently used deep clicks are: 
« Switching from the declaration of a symbol to its implementation by 
<Ctrl>clicking on the symbol in the symbol list of the Editor 
# Restricting the information shown in the list of a Symbol Browser by 
<Ctrl>clicking on the checkbox of a project in the project tree view 


« Showing methods of only one class in the Class Browser by <Ctrl>clicking 
on the class in the inheritance graph view 


Fast positioning in lists Pressing a key while the mouse pointer is over a list will position the list to the 
first entry whose name starts with that letter. 


The following sections describe how the environment must be for you to use this 
manual and run SNiFF+ successfully. 


Installation The SNiFF+ product package is installed automatically when the entire Taligent 
product is initially installed. The source directory for all SNiFF+ files is 
$TALIGENTROOT/$TOOLS/SNiFF. For more information regarding the installation, 


see the Taligent installation guide or ask your system administrator. 
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Checking the SNiFF+ needs two environment variables. The environment variables should 

environment already have been set by your system administrator. The following instructions 
show you how to verify their values, and to correct them if needed. If the 
variables are not set correctly, you set them in your .login or .cshrc file. 


“°2 NOTE The environment variables and license file are set as part of the 
installation procedure. Use the following settings for reference—you should not 
need to complete the procedures. — 


SSNIFF_DIR In the shell type 


1s $SNIFF_DIR 


If you see a list of files containing bin, examples, doc and some others then the 
variable is set correctly. 
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If not, set the variable by typing in the shell 
setenv SNIFF_DIR <sniff_directory> | (for csh) 
SNIFF_DIR=<sniff_directory>; export SNIFF_DIR (for sh or ksh) 
where <sniff_directory> is the root of the directory tree of your SNiFF+ 
installation. You can get the location from the Taligent installation guide or the 
person who installed the Taligent product (normally the system administrator). 
$PATH In the shell type 
echo $PATH 
If you can see <sniff_directory>/bin somewhere, then it is OK. 
If not, set the path by typing in the shell 
set path = ($SNIFF_DIR/bin $path) (for csh) 
PATH=$SNIFF_DIR/bin:$PATH; export PATH (for sh or ksh) 
“NOTE You will not be able to compile and debug the example applications in 
this manual. Therefore the executable search path does not contain compiler or 
debugger names. 
$LM_LICENSE_FILE (2NOTE $LM_LICENSE_FILE is set automatically by the Taligent installation 


procedures. The following information does not apply to Taligent users. 


The $LM_LICENSE_FILE variable has to point to a valid license file. 


The license file can also be specified with the -c command line option of sniff. 
The following setting shows a configuration where the license file is located in 
the SNiFF+ installation directory: 


setenv LM_LICENSE_FILE <sniff_directory>/license.dat (for csh) 


LM_LICENSE_FILE=<sniff_directory>/license.dat; (for sh or ksh) 
export LM_LICENSE_FILE 
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Copying the example You have to copy the example source files to your home directory because you 
files to your local will modify them during the following sessions. 


directory In the shell type 


sniff_copy_example 


This shellscript creates the directory ~/filebrowser and copies the files into it. 
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SNiFF+ command line =The command line syntax of SNiFF+ is 


sniff [-c <license_file>] [<project_file>] 


where the optional <project_file> is the name of an existing SNiFF+ project file 
and <license_file> points the license file to be used. Please refer to the 
Installation Guide for more information on licensing issues. 


tarting SNiFF+ from In the shell where you checked the environment variables type 
shell . 
sniff 
or 
sniff & 


SNiFF+ should come up and you should see the empty Workspace Manager 
window: 


List of projects | 
(currently empty) 
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In this section you will create the filebrowser project, load the already existing 
source files into SNiFF+, and add the ET++ project as a subproject. The ET++ 
project is loaded as a subproject because the filebrowser project is based on 

1 
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Choose “New...” from the Project menu of the Workspace Manager. 


filebrowser project A Directory Dialog is opened, prompting you for directory where the source 


files of your project are located. 


Select the ~/filebrowser directory in the file list by clicking on it. 


You can navigate either using the file list of the Directory dialog, by clicking 
at the directory pop-up menu, the Directories menu, or by manually typing 
in the directory name. 


Directories menu remembers the history of 
selected directories. 
Options menu can be used to create a directory 


Directory pop-up menu 


Only allows you to go up in hierarchy 


directories 
are listed 


(Mailboxes 


(CUSNLFF+1.0.1 

List of directories 

Pressing a letter on the keyboard positions 
the list at the first entry whose name starts 
with that letter. 

The PageUp/PageDown keys also scroll the 
list 


Opens the .. Selects the 
current current directory 
directory 
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NOTE Each Directory dialog and File dialog expands C-shell metacharacters 
such as '~' (for the home directory) or environment variables (for example, 


$SNIFF_DIR). 


Press the Select button (If you are in the directory and can see the source 
files, type '.' and press the Select button). 


M4 Press “Yes” to load all C/C++ files located in the directory. 


A Project Editor is opened, all sources files are parsed, and the symbolic 
information is loaded into SNiFF+. 


After the files are loaded you are asked whether to save the yet untitled project. 
Press the Yes button. 
A File dialog is opened, prompting you for the name of the project file. 


f4 Position the mouse pointer on the text field of the File dialog and type in: 
filebrowser.proj 


Press the Save button or <Enter>. 


NOTE A project file stores only structural information and attributes of your 
project. No source code or symbolic information is stored there. 
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The Project Editor should look like this: 


Icon 
menu 
----- Filter regular expression 
currently allowing all files 
cowserCmdNa. hk : : ' 
oe ie Pressing the button shows locking and version 
auceruce dh control information 
rowserItems. 0 
rowsercltems.h 
rowserView. C : : 
rowserView. h ES List of files 
| changeDirDiag. ¢ determined by project tree settings and Filter 
hangeDicbiag. h . 
llebrowser.C 
references.C 
references.h 
haredDocObjects. 0 
haredDocObjects.h Layout Handle 
allows modification of the size ratio between the two views 
Project tree 
showing the project structure and the attributes 
—---- Show files in file list 
Link objects to target 
scene Project is writable 
Tool is — 
reusable 
Setting the project Next you have to specify some attributes for this newly created project. 


attributes Select the newly created project in the project tree by clicking on it. 


Choose “Attributes of Project filebrowser.proj” from the Project menu or 
double-click on the project in the Project tree. 


A Project Attributes dialog is opened. 
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Directory where SNiFF+ stores the generated 
project-specific files 


Important for debugging: class prefix of ET++ 


Command called on make requests 


Underlying version control system 
Path used for the version directory 


Object files should be linked to the 
target 


Project is not a library; files may be modified 


Defining the targetname, ‘The target name is important because SNiFF+ uses it to drive the compiler and 


tab length, class prefix the debugger. The tab length has to be set to 8 because ET++ was developed with 
and version control that setting and the SNiFF+ default value is 4 (see “Preferences” on page 231). 
system 


Type filebrowser in the target field. 


Press the <Tab> key twice to set the keyboard focus to the tab width field and 
type in 8. 
In the class prefix field type ET_. 


“@ NOTE In order to debug the example application, the class prefix field must 
be filled out correctly 


Za Select “RCS” from the Tool pop-up menu of the Locking Parameters. 
Another possibility is “SCCS”, but Taligent does not use it. 


Press <Enter> or click on the OK button. 
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Checking the source You have chosen “RCS” as the underlying version control system. To work with 


files into the version the version control features of SNiFF+, you have to check in the files. 
control system Press the “Show Locking” button. 


The Project Editor changes its layout and shows the additional components 
for the version control system. 


Press the “Select All” button. 
All entries in the list are selected. 


Press the “Check In...” button. 


A Log Message dialog is opened, prompting for a message to be stored with 
the initial version. 


EY Type in Initial Version and press “OK”. 
The Project Editor should look now like this: 
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BrowsercView.h 
ChangeDirDiag. C 
ChanqgeDirliag. h 


++* enpty descraption +7* 


on 1.1 
d 1993/09/03 14:35:41; 


author: chris 
Initial version 


s; lin 


Press the “Hide Locking” button. 


The Project Editor is switched back to the initial mode and hides the version 
control information. 


TALIGENT CONFIDENTIAL: REGISTERED INFORMATION TALIGENT TOOLS FOR AIX 


141 


142 CHAPTER 10 GETTING STARTED 
CREATING A NEW PROJECT 
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Loading a subproject The filebrowser is based on the object-oriented application framework ET++, 
which is in the public domain and is also part of the SNiFF+ distribution. ET++ 
was already loaded into SNiFF+, so there is an already existing project file. 


# 
2 a 


subproject only if it is a SNiFF+ project itself. 


Choose “Load Subproject...” from the Project menu of the Project Editor 
(filebrowser.proj must still be highlighted). 


Now you see the File dialog prompting you for the project file. 


Select $SNIFF_DIR/examples/projects/et.proj and commit. 


The symbolic information for ET++ is loaded and the project tree of the 
Project Editor shows the new project structure. Since ET++ itself has a 
subproject called CONTAINER. proj, this structure is also shown in the 
project tree. 


Investigating the Select et.proj in the project tree. 
attributes of the 


ET++ subproject Choose “Attributes of et.proj...” from the Project menu. 


The Attributes Dialog for et .proj is opened. 


You are not allowed to change the parameters because et .proj is a frozen 


project, meaning that no files may be modified. You can also see that the object 


files of this project should not be linked to the target. 
Close the Attributes dialog by clicking the “Cancel” button. 
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aBrowserCmdNo. k 
{BrowserDoc. ¢ 
{BrowserDoc.h 
{BrowserItems. 0 


qBrowserltems. h 
EcowserView. C 
{BrowserView. h 

q ChangeDirbiag. ¢ 
qChangeDirDiag. h 
qfilebrowser.C 
Preferences. C 
iPreferences.h 
SharedDoacObjects. C 
dSharedDoc0bjects.h 


EA ly filebrowser. proj l | 
a nk [ee Subproject of filebrowser.proj 


pc]L_] CONTAINER. pro} Subproject of the et.proj subproject 
ee eee: | Soon Don't show files in file list 
- Don't link objects to target 


| 
| 


Project is frozen and may NOT be modified 


If not, close the newly created project in the Workspace Manager and restart 
from scratch. 


MELD AA TCURSECNIDS ER EASR PROC EOP OO ENE ASL OS UN READ CELA SCE ACAD P ERECT CLC O RL EOER EEE RRELU EER CHD CLEES 


Saving the new project The project creation is finished now and all that is left to do is to save the project 
and closing the Project specifications to a project file. From then on the Project Editor is only needed 


Editor 


PRELIMINARY 


when the structure changes or attributes have to be edited. 


Choose “Save Project filebrowser.proj” from the File menu of the Project 
Editor. 


Choose “Close Tool” from the Icon menu. 


The only open window now should be the Workspace Manager. 
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CHAPTER 11 


UsING SNIFF+ 


The handling of the Symbol Browser, the Class Browser and Retriever is very 
similar. Therefore the common parts of the browsers are described once while 
working with the Symbol Browser. ———es 


+ 
ere Teer Peer eee P rere ee tree te etre eee ee ee eee ee eee eee eee ree tee eee eee eee e eee ee Pee tee TTT eer eter eee ere Tee eee eee Terre rete eer ee Leer see Eee eet ee eee eee eee 


Opening a Select the filebrowser.proj in the Workspace Manager by clicking on it. 


Symbol Browser Choose “Symbol Browser” from the Icon menu. 


A Symbol Browser is opened listing all classes. 


Click on the et.proj check box in the project tree at the bottom of the 
window. 


The classes of et. proj are now also listed. 
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Icon 
menu 
Filter regular expression (currently allowing all symbols) 
Type pop-up menu 
fackgroundI tem 
batchInfo (struct: WindowPort.h 
: List of Symbols 
}itmapCache determined by type pop-up menu, Filter, and 
Bete inee project tree settings 
itSetIter 
lock 
orderIten 
oundedConmmandProcessor 
HO 
irowserapplication 
cowserDocument j= j #2 33. Layout Handle 
allows modification of the size ratio between the two views 
filebrowser. proj 7 Project tree 
ly} et. proj } : 
-] CONTAINER. pro; showing the project structure 
Symbols are not shown in list 
ee Coe Filter also matches part of a word 
Tool is 
reusable 
Generally speaking, the Symbol Browser shows a list of symbols which is 
determined by the type selector, the project tree, and a regular expression 
matching the names of the symbols. 
Relation to the Every symbol of the list is defined in the source code. You can jump to the 
source code position in the source code defining the symbol by double-clicking on it. 


Double-click on the symbol named ActionButton. 


An Editor is now opened, the source files are loaded, and the cursor is | 
positioned to the location defining/declaring the symbol. 


“NOTE Pressing a key in a list will position the list to the first entry whose 
name starts with that letter. 


You will have a closer look at the Editor later. 


Select “Close Tool” from the Icon menu to close the Editor. 
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Pralact’ tree 


Restricting information 
shown in the symbol list 


PORORPEL APL IPP LL OD AOSD DPD ALPIPPLIOL PLE POL IL IID DIOP IP OLDI BOPP EPPILADIA LLP ODDO ES 
C t i t h 


list with filters 


Setting a filter 


Resetting the filter 
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The project tree shows the hierarchical structure of the project the browser 
belongs to. The check boxes in front of the project names determine if the 
corresponding symbols are shown or hidden in the symbol list. 


Symbols can be shown/hidden by directly manipulating the check boxes or 
issuing a menu command after selecting a project entry. 


Switch the check box of the et.proj on and off and watch the results. 


Choose “Select from all projects” from the Filter menu. 


Now you see the classes of all projects, including the subprojects of et.proj. 


Click on the filebrowser.proj entry (not on the check box of the nny): 
The entry should be highlighted. 


EI Choose “Select From filebrowser.proj Only” from the Filter menu. 


Only the classes of filebrowser.proj are displayed; the classes of all other 
projects are hidden. A deep click (<Ctrl>click) on the entry (not on the 
check box of the entry) gives the same result as the “Select from _ 
filebrowser.proj only” command. 


SNiFF+ allows you to restrict the list of the browsers to entries matching a regular 
expression. This feature is very helpful when many entries are in the list and you 
want to focus only on a subset of them. The regular expression is also called a 
filter and conforms to the powerful GNU regular expression syntax (see “GNU 
Regular Expressions” on page 257). 


Let us set a falter to view only classes starting with the letter B. 
Also view the classes of the et.proj by toggling the et.proj check box to on. 
Choose “Set filter...” from the Filter menu. 


A dialog pops up prompting you for the filter. 


Ei Type in *B and press <Enter> (the '"' in front of the B is correct and 1 means 
beginning of line). 
You see that only classes beginning with B are listed. 


Because regular expressions are a powerful tool to limit the amount of 
information, they are also used in the Class Browser, in the Retriever, and in the 
Find/Change dialog of the Editor. 


M Choose “Reset filter” from the Filter menu. 


All classes are listed now. 
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Type pop-up menu The Symbol Browser can show symbols of different types and macros. Besides 
classes, you can look at functions, friends, variables, types, etc. Methods can also 
be shown. (The list of methods can get very long, because it is a flat view of all 
methods of all classes if not further constrained). 


In the project tree check the box of et.proj to show its symbols. 


Try to show functions, macros, types, etc., by selecting different types from 
the type pop-up menu. 


Switch back to classes. 
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‘TOP-DOWN BROWSING 


Top-down browsing is when you have a symbol, e.g., a class, and you want to learn 
more about its details and where and in what context it is used. Figuratively 
speaking, you are coming from a more distant view of your system (you just know 
that there is a class with that name) and are browsing down to the source code 
(bottom) and greater detail. 


You will study this type of browsing now with the class ActionButton. During the 
following step-by-step tour you will start with the already familiar Symbol Browser 
and make acquaintance with the Hierarchy Browser, the Class Browser, and the 


Editor. 
Viewing ActionButton View all classes in the Symbol Browser (including classes from et.proj). You 
in the class hierarchy can do this by switching on the check box of et.proj in the project tree. 


Select class ActionButton in the Symbol Browser. 


Choose “Show Class ActionButton in Hierarchy” from the Class menu. 


A Hierarchy Browser is opened showing the complete class graph and 
focusing on the class ActionButton. 


4 
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Icon 
menu 
Normal class 
| | 
\PreeNode GraphNode 
| p»scrollbarBbutton : 
/ Inheritance 
relationship from left 
f MenuButtontl tem to right 
ij Vob jectButton 
ae Absiract class 
‘ go ee containing pure 
‘ MenuButton <— PullDownb virtual methods 
Tool is - 
reusable 
Try to get an overview of the class hierarchy and the inheritance path of our 
class by scrolling around. 
NOTE Although we use only single inheritance in our examples, the SNiFF+ 
tools also support multiple inheritance. 
Loading all classes into the Hierarchy Browser allows you to get a good overview 
of the complete class hierarchy. However, you will find it very hard to follow an 
inheritance path up to the root without lots of scrolling. Therefore you will 
restrict the view to ActionButton. 
Too much information— Select the class ActionButton in the Hierarchy Browser (if it is not already 
restrict information to selected). 


ActionButton 
Choose “Show Class ActionButton in Restricted Hierarchy” from the Class 


menu. 


Now the view is restricted to show only the superclasses and subclasses of 
ActionButton. All other classes are hidden. Since ActionButton is a leaf class, 
no other classes inherit from it. The information you get is now too limited. 
You get the best results for our purposes by restricting the view to the abstract 
base class of ActionButton, namely Button. 


“@NOTE All tools print abstract classes in italic. 


PRELIMINARY TALIGENT CONFIDENTIAL: REGISTERED INFORMATION TALIGENT TOOLS FOR AIX 


(150 CHAPTER 11 USING SNIFF+ 
TOP-DOWN BROWSING 


Too little information— Select the class Button in the Hierarchy Browser. 
restrict information to ; ; 7 | 
Button | Choose “Show Class Button in Restricted Hierarchy” from the Class menu. 


Now the view is restricted to show only the superclasses and subclasses of 
Button. All other classes are hidden. This gives you a better picture of the 
inheritance that leads to ActionButton and related classes. 


; ScrollbarButton 
| JActlonButton 


; MenuButtoniItem 


e yobjectButton 
: - 


ae , . 
veozect Composz teVedzect Be ie v RadioButton 


es 
™, ol 


*S. StateButton & — To ggleButton 
~ PopupButto 


, a 
*\ MenuButton <— PulldowmBu 


SS Merultem 


This is the context of our class in terms of inheritance. You will return to the class 
hierarchy later. Now you concentrate on the internals of ActionButton. 


PALL LISP PIID, 1 ODAM. PP PLIEPLILALIISDPLPIPLPPLISLILIPIL IIL DS PLDPLLIPLPLPILIIPIISPLILILSLLLPPPPLSLLPLLPISPSIPLLPIIPLI SLL LILISPLIPILISLIS DIL ID 2, 


Browsing the elements With the Class Browser you can browse the internal structure of a class (in this 
of ActionButton— manual local symbols of a class are called elements). The structure of the Class 
the Class Browser Browser is very similar to the Symbol Browser. | 


Select the class Button in the Hierarchy Browser (if is it not already selected). 


Choose “Browse Class Button” from the Class menu. 


A Class Browser is opened and the information about class Button is loaded. 
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Icon 
menu Name of class being browsed 
Filter regular expression (currently allowing all symbols) 
Type pop-up menu 
[] Button Buttor 
CL] DoLeftButtonDownlt Button 
DoTrackMouse Button 
[] DrawHighlight Button 
Borer List of elements | 
Visibili Eee determined by type pop-up menu, filter and inheritance 
ee! apn ecu raph settings 
white: public [] Set0rigin Button grap g 


gray: protected 
black: private 


Layout Handle 
allows modification of the size ratio between the two views 


Button _.~ Inheritance Graph 
|_| robe teVoojzect showing the inheritance path with all superclasses 
vaozect 
pipe? Don't show local elements in list 
| | Object 
- All elements are shown, including overridden ones 
Tool is 
reusable 
Structure of the The Class Browser lists the elements of the current class identified by the element 
Class Browser name and the name of the class defining the element. The small squares in front 


of the name show the visibility of the element 

# White is public. 

# Grey is protected. 

# Black is private. 
Like the Symbol Browser, the Class Browser also has a type pop-up menu. Here 
you can choose among methods, instance variables, friends, types, or local 


enumerations of the current class. The list can be filtered with a regular 
expression. 


Where the Symbol Browser has a project tree, the Class Browser has an 
inheritance graph reflecting the inheritance path. Each class can be toggled on 
or off individually. 


M@ Check the box of class CompositeVObject in the inheritance graph. 


You will recognize that not only the methods of class Button are displayed 
but also of class CompositeVObject. 
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What overrides what? M@ Choose “Select From All Classes” from the Filter menu. 


Now you have a completely flat view of the class Button including all 
overridden methods. Each entry in the list shows the method name and the 
class defining the method. So you see what overrides what. Method Add, for 
example, is introduced in VObject and overridden in CompositeVObject. 


Hiding overridden A completely flat view of the class is not always useful. Sometimes you want to see 
methods just the interface of the current class, hiding all the methods that are overridden. 


M@ Press the button labeled “hide overridden” at the bottom of the Class 
Browser. 


Now only the client interface of the loaded class is visible. 


PEL OL OL LOL O PEOPLE ID, 


Studying protocols Very often when browsing software systems you would like to know what overrides 
a certain method. SNiFF+ supports that type of protocol browsing by combining 
the Class Browser and the Hierarchy Browser. 


Load the class Button into the Class Browser (if it is not already there). 


You can do this by loading it from either the Hierarchy Browser or the 
Symbol Browser. 


Select method Button: :GetMinSize. 


You can do this either by scrolling or by pressing the key 'G' (which positions 
the list to the first method starting with G). 


Choose “Mark Related Classes Defining GetMinSize” from the Class menu. 


The Hierarchy Browser is opened and all classes related to Button are 
loaded. 


All classes displayed in boldface override the method GetMinSize. The Hierarchy 
Browser informs you about the marking in the status line. 
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F ScrollBarButton 
: ActionButton 
f : MenuButtonIten Marked class 
/ ,vobjectButton overriding 
VObj ect —— Compositevobject —— Buittant ie eee tens GetMinSize 
, ebut ton ae ToggleButton 
‘. ae ane Not defining 
\MenuButton — PulldownBut GetMinSize 


“S. Menultem 


Semantics of 
marking 


Viewing the source code By selecting boldfaced classes in the Hierarchy Browser, you can view the source 
code of the overridden methods. 


Select ActionButton. 


Choose “Edit Method GetMinSize” from the Hierarchy menu. 


_ An Editor is opened, class ActionButton is loaded, and the cursor is 
positioned at the method implementation. 


‘Try to look at the implementation of GetMinSize of some other classes in the 
Hierarchy Browser. 
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Bottom-up browsing is when you start from the source code and you look at a 
symbol, e.g., a variable, and you would like to know more about its declaration 


and definition. 


Figuratively speaking, you are coming from a special-usage context (source code, 
therefore bottom) and are browsing up to its declaration (higher view). 


You will study this type of browsing, continuing where you stopped in the last 
section, namely with the implementation source code of 


ActionButton: :GetMinSize. 


During the following step-by-step tour you will start with the already familiar 
Editor and make acquaintance with the Retriever. 


aa eee Re Cee LMA EA A DALES CE EEL EA EEE L EE LOE E LEEDS EE EAM ERASE LEEDS OEE CEREAL E REE ACE CEREAL ERATE LEED 


Studying the method 


Load the source of ActionButton: :GetMinSize into the Editor (if it is not 
already loaded). You can do that from the Class Browser, the Hierarchy 


You see that the variable gLook is used in the context of a method call. 


GetMinSize 
Browser or the Symbol Browser. 
Study the method. 
Icon menu ---. - 
reflects editing 
state } 
: read-only Metric ActionButton: : 8 
- not modified { Be 
- modified if (TestFlag(eActionDefaultButton) } 


currently: r/o 


Symbol names... 
are printed in 


bold int code= 0; 
if fEnabled(i) 
SETBIT(code, 2); 
if (highlight) 
SETBITicode, 3); 
if (TestFlag(eActionDefaultButton) } 


return gLook->DefaultButtonLayout () ->GetMinSize (this) ; 
return gLook->ActionButtonLayout () ->GetMinSize (this) ; & 


void ActionButton: :Drawlmer (Rectangle, bool highlight) 


- Class pop-up 
menu either 
shows all 
classes or only 
one class 
(current setting) 


ActionButton (m1) 
ActionButton (m1) 
Gontroltmi} 
Drawinner (m1) 


Symbol list 
defined by class 
pop-up menu 
(clicking on a 
symbol 
positions the 
cursor) 


gLook->DefaultButtonLayout (j ->Adorn(this, contentRect, 


else 


gLook-2ActionButtonLayout()->Adorn(this, contentRect, c 


reusable 


TALIGENT TOOLS FOR AIX 


Layout Handle 
allows 
modification of 
the size ratio 
between the two 
views 
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Browsing the 
declaration of gLook 


Continued browsing— 
what is Look? 


Going back in history 
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Double-click on the name gLook in the Editor. 


Choose “Find Symbols Matching gLook” from the Info menu. 


SNiFF+ opens a Symbol Browser and tries to find a symbol of any type 
matching gLook. : 


The Symbol Browser finds one symbol of type variable matching gLook. If there 
were any matches for other types, too, you could see this by clicking on the type 
pop-up menu. If no other entries are enabled, there are no other matches, which 


is the case for gLook. 


M Double-click on gLook in the Symbol Browser. 


The source code declaring gLook is loaded into an Editor. gLook is a global 
variable and refers to an object of class Look. Now you should learn more 
about Look. 


Select Look in the Editor by double-clicking on its name. 


Choose “Browse Class Look” from the Class menu (the entry is enabled 
because SNiFF+ knows that Look is a class). 


The class Look is loaded into a Class Browser. 


Load the source code of some methods of Look into the Editor by double- 
clicking on entries in the Class Browser. 


Za Close the Class Browser. 


After browsing a lot, you seem to be lost somewhere in the source code. Didn't 
you start originally from the usage of variable gLook somewhere in 
ActionButton? Now you need the history feature of SNiFF+. 


Click on the History menu of the Editor. 


What you see in the pull-down menu are all the locations in the source code 
of our system you have visited during the browsing session. 


Choose “gLook (Look.C)” from the History menu. 
The Editor jumps back to the declaration of gLook. 
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An alternative to the 
history mechanism— 
tool locking 
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Where glook is used— 
the Retriever 


Retrieving gLook from 
all projects 


There is an alternative to jumping back and forth in just one Editor. By default 
every tool is reusable; that means whenever SNiFF+ needs a tool, it searches for 
an open tool of that type and uses it for the request. It opens a new tool only if 
there is no tool available. This feature prevents screen n cluttering and too many 
open windows. 


You can lock any tool of SNiFF+ against automatic (re)usage by releasing the 
“reusable” button in the status line. This feature is useful when writing code and 
simultaneously browsing two or more source files. Any browsing request will then 
open a new kditor. 


Release the “reusable” button of the status line of the open Editor. 


Double-click on any symbol in the Symbol Browser (currently only gLook is 
loaded, but you can load all classes into the Symbol Browser by choosing 
“class .*” from the History menu). 


A new Editor is opened, leaving your locked Editor untouched. 


“{@ NOTE You can have as many instances of a tool as you like. After you lock a 
tool, SNiFF+ will not reuse that tool, but will open a new tool on a browsing 
request. It is good “SNiFF+ing style” to work with as few tools as possible 


PPLE LOLI ELLE LT ECT LEEOL ELLE CET LOLOL EET OEE ECCT OL LEE 


In the previous session you started from ActionButton: :GetMinSize and browsed 
the variable gLook. 


Now you want to know where else in our software system this variable is used. The 
Retriever is a tool that allows you to find any matches in the whole project. 


@ Load the declaration of gLook into an Editor (if not already there). 


You can do this by double-clicking on gLook in the variable list of the Symbol 
Browser. 


Double-click on gLook in the Editor. 


Choose “Retrieve gLook From All Projects” from the Info menu. 


After a few seconds a Retriever is opened and the usages of gLook in our 
project, including all subprojects, are listed. This is too much information 
for us. Let's restrict the list to the places where gLook is assigned a value 
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Icon 
menu 
Search 
string 
qLook return gLook->MenultemLayout () ->GetMinsize ( thi: 
gLook gLook-?MenultemLayout()->SetOrigin(this, at); List of matches 
gLock gLook->MenultemLayout(} ->Adorn(this, contenthe: filename, 
qLook Metric m(qLook->SashLayout () ->GetMinSize (this; : match, 
qLook gLook->SashLayout()->Adorn(this, ©, 0); source line 
gLook GrShowString(font, Enabled{} ? gInkBlack : gLo: 
qgLook Look *gLaok; 
gLook gLook= looks[currentlook] ; Layout 
gLook gqLook= looks[currentlook] ; Handle 
gLook GrPaintbitMap(contentRect, bmp, Enabled() ? eP:. allows 
: qLoak { le title? grOGr 2 Ee pUppenubeyoee) > gLook modification 
Jindows; qLook { l= <- >PopUpMernuLayout () gLook of the size 
ratio between 
the two views 
y¥| filebrowser. proj 
jet. proj 
Also [| CONTAINER. proj - Project tree 
search this 
project 
Tool is 
reusable 


Case sensitive Also match part of a word Number of matches 


Choose “assignment” from the Filter menu of the Retriever. 


What you see now are the two locations in our 60KLOC project where gLook 
is assigned a value. 


The Retriever uses a two-stage filtering process: 


# At first all lines matching the search string are extracted. 


# Then the list is once more restricted by the regular expression (in this 
case a regular expression representing the syntax of an assignment). 


NOTE The Retriever starts a full text search (like a super-grep in UNIX) over 
the project files and adds flexible semantic filtering as a second stage. 


Of course, you can also load the code of the matches into an Editor. 


£3 Double-click on a match. 


The source code is loaded into an Editor. 
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Retrieving session2— The Retriever is a very powerful tool for formulating fuzzy queries. Let's try to get 
getting information all positions in our project that have something to do with menu handling. 


about menu handling Type Menu in the text field of the Retriever and press the Ignore case button 


in the status line. 


Press the Retrieve button or <Enter>. 


The Retriever lists hundreds of places (you can see the exact number in the 
status line). That's too many. 


NOTE After the first retrieve, the source code is cached and all further 
queries are much faster. You can switch caching off in the Preferences Dialog. 


Let's apply the assignment filter. 


Choose “Assignment” from the Filter menu. 


Now you have the locations in your project where a variable called “menu” or 
similar is assigned a value. 


Where are menus To get this information, you only have to apply another filter. 


allocated on the heap? 
P M Choose “new” from the Filter menu. 


Now you get about 60 locations in our project where a menu or something 
related is allocated on the heap 


‘“2NOTE The Retriever is a text retrieval tool with semantic filtering. It works 


hs ‘ 


best when the software system has consistent naming. 
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SNiFF+ provides its own integrated Editor for editing source code. This section 
describes how to work with the integrated Editor. SNiFF+'s WYSIWYG Editor 
serves not only editing but also browsing purposes. It partially understands the 
C/C++ syntax and can format the text with different fonts and colors. | 


ee 


“s NOTE Font and color settings for the formatted source code can be specified 
in the ETRC file. For more information see “Preferences” on page 231. 
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Loading a symbol into 


the symbol in the Symbol Browser. 


type via the type pop-up menu 


CHAPTER 11 


NOTE It is possible that you still have the gLook variable match in the 
Symbol Browser. If so, reset the filter and switch from the variable type to class 


The class is loaded into an Editor and the cursor is positioned to the 


declaration of BrowserView. 


Icon menu 
reflects editing 
state 

- read-only 

- not modified 
- modified 
currently: r/o 
Symbol names 
are displayed 
in special font 
faces 


I protected: 
: Seqlollection *path, *directories; 
ComposiateVObj ect *#ifezzsts; «* shown £2 


ChangeDircbiag *changeDzr ; 


void LoadFiletint at. FileList *f1); 


public: 
MetaDef (BrowserView) ; 


ge 


int n&how; ee pumder of 
int left; (f iadex oo 
VObject, +shiftieft, *shiftRight ; ff oa 


ttons 


void Shelliint at, char *path, char +cmd= 0); 


BrowserView(EvtHandler *dp, int numFilelists) ; 


__ BrowserView(); 


Comments 
are displayed 
with a special 


ffor-- respond te user znput 


bool GrabKeyToken (Token &t) ; 


font face yoid DoSetup(} ; 
ff---- directory Aandling 
SeqGollection *ReadDirectory() ; 
void Showirectory(int at, char *name); 
void ShowParentDirectory () ; 

Tool is 

reusable 


void Comtrolf{int id. int detail, void *data); 


BrowserView (md) 
ClassDecl (md) F 
Control {md} Bro 
CreateFunctionte 
DirectoryNameat 

DosSetup (md) Bro 
FileBrowserPPrin 
FileBrowserPPrin 
PileBrowserText¥ 
FileBroyserText¥ 
FileListat {md 

FileListat (mi) 

Function (mdi Fi 
GoteFunction (md 


ReadDirectory tm 
RemoveandFreeLas 
ResetFunctionMen 


” us 
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Class pop-up 
menu either 
shows all 
classes or only 
one class 
(current setting) 


- Symbol list 


defined by class 
pop-up menu 
(clicking ona 
symbol 


positions the 


cursor) 


_ Layout Handle 


allows 
modification of 
the size ratio 
between the two 
views 


Because the BrowserView class belongs to the filebrowser project and the project 
is writable, you are allowed to modify this file. The status of the file is indicated by 
the tool icon at the upper left corner of the Editor. 


File is read-only File is writable 
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Symbol list 


Switching between 
declaration and 
implementation 


PLPPPPISLL EPIL PIL LPL ILL PEPPILIPDLPELIPLPLDISPPISLPLIISIDLELI OPI PEP IOIP, 


functions) of this file. It can be constrained by the pop-up menu just above the 
list. You can either select all classes or only one class. On a click on one symbol, 
the Editor immediately positions to the source code location defining the 
symbol. It also allows fast switching between declaration (normally in -h files) and 
implementation (normally in .C files). 


ou Try positioning by clicking on various symbols in the Symbol list. 


Choose “FileBrowserTextView” from the class pop-up menu above the 
Symbol list. 


Switch back to the “BrowserView” context. You can do this either by selecting 
it from the class pop-up menu or by using the History menu. 


With <Ctrl> mouse click on the symbol, you switch between declaration and 
implementation of the selected symbol. 


<Ctrl> click on BrowserView (md) in the Symbol list. 


The Editor now shows the implementation of BrowserView::BrowserView. 


Try some other entries. 
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-§ NOTE You can check out the file only if you have selected a version control 
system and checked in the files. See “Checking the source files into the version 
control system” on page 140. 


The loaded files are read-only because we have checked in all project files before. 
To modify a file, you have to check out and lock the file. 


Load the implementation of BrowserView into the Editor (file 
BrowserView.C). 


Choose “Check Out” from the File menu. | 


The file is checked out and the editing state changes to writable. If you would 
open the Project Editor, you could see that the latest version of the file is 
locked by you. 
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Sani iisétul | editing The Editor offers a lot of help that makes your life as a programmer easier. There 
helps are features like multilevel undo, matching brackets, nesting and unnesting, 
commenting and uncommenting, etc. 


= NOTE SNiFF+ always keeps the locations of symbols in the source text up-to- 
date, even after inserting or deleting lines. If a modified file is saved, all tools will 
immediately update their views to reflect the newest set of symbols. 


Matching brackets Double-click to the right of the opening parenthesis of the last Add statement 
and quotes in BrowserView::BrowserView. 


The Editor marks the text to the closing bracket. 


Nesting and unnesting, Select the last Add statement in BrowserView::BrowserView completely. 
commenting and 


: You can do this by double-clicking left to the Add and dragging the mouse 
uncommenting 


down. to the last closing parenthesis while holding down the mouse button. 
Choose “Comment” from the Edit Menu. 
The complete statement is commented out. 
“f aimitzaiize feft most File 22st 
ShowDirectory{-1, "."); 


Add (fileLists) ; 


J 


Undo the changes by choosing “Undo” from the Edit menu. 


NOTE SNiFF+ allows an arbitrary number of undo levels. The number of 
undo levels can be set in the ETRC file (see “Preferences” on page 231). 


Don’t save the modifications you have made. 
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VIEWING AND EDITING CLASS AND MEMBER DESCRIPTIONS 
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Documentation 
Browser 


In this section, you will begin working with a Taligent project. Before you begin, 
close the current project. 


Use the Icon menu to go to the application window. 


Close filebrowser.proj. 


The Documentation Browser allows you to view and edit class and member 
function descriptions. Taligent source and documentation files are accessed from 
a prebuilt project called Taligent.proj which is located in 


$TaligentSystemDocs/TaligentIncludesDocs/Public 


The Taligent Application Environment class and member descriptions are stored 
in the Docs subdirectory of the Public directory. The Manual Path preference 
determines where class and member descriptions are found. See “Preferences 
dialog” on page 232 for more information on preferences. 


To load the Taligent project: 


From the Project Editor File menu, choose “Open Project...” and select 
Taligent.proj. 


Double-click on Audio.h to display the file in the Source Editor. 


The Documentation Browser is similar to the Source Editor, but you view and 
work on the associated .d files. 


In the Source Editor, select GetFormat (md) from the class list. 


Choose “Show Documentation of GetFormat” from the Info menu. 


The Documentation Browser displays the Audio.d file and the description of 
GetFormat. 


es 


€@NOTE You can also start the Documentation Browser without a file displayed 
by selecting Documentation Browser from the Icon menu. 
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Icon menu 


reflects editing 


state 
- read-only 


- not modified 


- modified 
currently: 
modified 


Tool is... --. 


reusable 


descriptions 
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| TAudiotype : :GetFormat 
: Tloken GetFormat (3 
jInterface Category: 
zy Same as class. 
iq Purpose: 
4 OGM PUR 
eY Calling Context: 
: XEEK_M CAL 
i Parameters: 
Takes no parameters. 
iReturn Value: 
SOO M_RET 
xceptions : 
Throws no exceptions, passes all exceptions through. 


Eaud oExceptions 
GetaLaw (md) 
GetALawsKHe (md) 


const 


XKEXK M INT 


GetLinearl6Bbit4s4kHs 
GetLinearabiteeKH. [ 


- S2000% M Park 


HDGKL M EEC 


| Concurrency: 

Same as class. 

gOthec Considerations: 
SG0EK_M_OTH 


opecator<<= {md) 
opercator= (md) 
operator>>= {md} 
PrintDebugInfo (md) 
SetFormat {mdi 
SetSampleRate (md) 
SetSampleWidth (md} 
TaudioType (cl) 
TaAudiolType (md) 
typedef char Samples 


SOOT M_CON 


§ TAudioType : :SetFormat 

wold SetFormat {const TToken &) 
fInterface Category: 
Same as class. EK M INT 
a Purpose: 
MGM PUR 
Calling Context 


PL EP LOLOL ELIE LOD, 


As with the Source Editor, a list of classes appears at the right. You can display all 
classes or view only one class. 


In addition, you can list the classes in alphabetical order or in the order they 


occur in the .d file by toggling the Alphabetically button at the bottom of the list. 


Click on any item in the list to view the description. 


ar. PPP OL. a At, PPMP OL OLS, PLOL PL EL PLL LEP LLL ILLES ILIA POOLE OILOLLLL LLDPE OEE OLD OPEL EDIE LIL ELLIS PP EL OLE LILELLD OAPI PPL PLLLLL LLL OL. 


Changing from read- 
only to writable 


PRELIMINARY 
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If the file is read-only, you can view the documentation, but you can’t change it, 
and obsoleted descriptions are not displayed. Check the icon to see if the file is 
writable. If you want to edit a read-only file, change the Preferences. 


Choose “Preferences” from the Icon menu. 


Press the button on the “Read-Only Documentation” flag to allow you to edit 
the file. 


The icon on the Documentation Browser changes to indicate the file is 
writable and obsoleted descriptions are displayed. 


Select OK to close the window. 
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Class pop-up 
menu either 
shows all 
classes or only 
one class 
(current setting) 


Symbol list 
defined by class 
pop-up menu 
(clicking on a 
symbol 
positions the 
cursor) 


Displays list 
alphabetically or 
in order of 
appearance in 
the file 


Merete ter ceet 


ew 
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diting the file You can select and type in the Documentation Browser the same way you do in 


the Source Editor. The Edit menu allows you to undo, redo typing, cut, copy, and 
paste. 


You can emphasize text or change it back to default font. 


CANA EL ONO LEE LEE AE EMMA EL EEL EELS ELLE ELC LEER CMLL LEE CE RARER E REEL ERIE EG CEE HE 


NOTE Checkin and Checkout functions are disabled in this release. 


checking out files 
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PEL LL LLL OL I SPIEL LEP LLL IL LALOR LILI LOL IL LOO LPI IEL IL OIEEL LLP DP LLP LILLIOIL LIES EOP LLLP LOLILID OL EPLELILIIPELLLE LEP IILLLILLLL IIL IP IEIPISELEILIL IL IID PEL I LEME L II ELELOIP AIG LEED ISLA SLL LLEPEL LLL AIA SEED IGE DPI II LILLE LOE IESL IIE INE 


PPP PLO P OPIN L ILE 


When you create your own projects in the Taligent Application Environment, you 
need to add Taligent public includes. | 


Open the Project Editor. Make sure the name of your new project is 
highlighted. | 


Choose “Load Subproject...” from the Project menu. 


Now you see the File dialog prompting you for the project file. 


Select $TaligentSystemDocs/TaligentIncludesDocs/Taligent.proj and 
commit. 
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COMPILING 


SNiFF+ delegates compiling to a compiler of choice and interprets its output 
messages to allow fast positioning in the source code. With the product package, 
we supply the GNU gcc compiling system. Unless your system administrator 
installed SNiFF+ with another compiler, gcc will be called now. Make sure you are 
working with filebrowser. proj. 


¢@ NOTE If gcc is not installed on your system, you should skip this section. 


Modifying the Load class BrowserView into an Editor. 
BrowserView class ae ; 
Position to the implementation of BrowserView::BrowserView. 
Find the line where a new ActionButton is assigned to shiftRight. 
Change the Label of the ActionButton from “>>” to “Down” 


-NOTE Immediately after the code is changed, the tool icon at the upper left 
corner changes to the modified sign. 


Insert an error by removing the comma ',' before the “Down”. 


shiftLeft = new ActionButton(cIdShiftLeft, “<<"); 
shiftRight= new ActionButto (cIdShiftRight. "Dow"); 


fi Save the file by choosing “Save” from the File menu. 


The tool icon changes back to its unmodified position. 
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Compiling BrowserView.o 


Jumping to the error in 
the source code and 
correcting it 


Icon 
menu 


reusable 


Building the target 
executable 


M Choose “Make File BrowserView.o” from the Make menu. 
SNiFF+ now opens a Shell and starts the compiler with BrowserView.C. Since 
you entered erroneous code, the compiler outputs an error. 

In the Shell click in the line where the error is reported. 


Choose “Find Error” from the Shell Menu. 


The Editor positions the cursor to the line containing the error. 


cd shome/chris/filebrowserII 


sunsb3% make = ~—~—~~—— ana En ; —_—-- Make called by SNiFF+ 


a Compilation error - 


Correct the error by inserting the comma ',' before the “Down”. 


fa Save the file. 


M@ Choose “Make Target filebrowser” from the Make menu (if this entry is 
disabled, you have forgotten to enter the target name in the Project 
Attributes dialog; see “Setting the project attributes” on page 138). 


‘Now make is called, the modified source file is compiled, and the target is 
linked 


eS 


@ NOTE In order to link the target, the correct target name must have been 


specified in the attributes of the filebrowser project (see “Setting the project 
attributes” on page 138). 
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click to it and select “Find 
Error’ from the Shell menu 
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SNiFF+ environment The SNiFF+ environment consists of several tools and processes: T 


data source for all tools is the Symbol Table, which is held in memory but is 


persistent between sessions. 


~ SNiFF+ 


Symbol 
Browser 
Data and Control Integrator 
| Sab | Project 
Table Manager 


pet rerctcictpalneenr 


Information 
Extractor 
(sniffserver) 


Retriever 


Other 


applications Ext. Access 
interacting Manager 


with SNiIFF+ 


Interapplication Debugger 
frontend 


(sniffgdb) 


message broker 
(sniffappcomm) / e 
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debugger back- | 
end (gdb or dbx) 


Subsystem 


SNiFF+ operating 
system process 


Foreign operating 
system process 


Member function call 


SNiFF+ tooltalk interface 


Stream connection (also 
via network) 


interapplication message 


command line interface 
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BASIC USER-INTERFACE COMPONENTS 


SNiFF+ provides eight tools. These tools have different purposes, but they share a 
lot of functionality in several pull-down menus and the status line. This section 
starts with a description of the commonalities. 


ELA OAL OE CLC CCL ELLER CLERC ELLA D EON ELEN A aE RE LEELA ELLE LEAL EL OBL OEE E REE KELERA LAE aR ECTS AED 


Status line All SNiFF+ tools have a similar status line at the bottom which displays status 
information. Status information can be either a boolean value represented by a 
toggle button followed by a text, and/or a nonmanipulable text showing some 


information. 


Toggle button determines the Status text; is 
reusability state of the tool not editable 


The reusable toggle button determines whether the tool can be reused in the 
case of a request or when a new tool has to be opened. 


NOTE Itis good “SNiFF+ing style” to work with as few (reusable) windows as 
possible. This habit prevents screen and information cluttering. 


Tool-specific status information is described in the corresponding tool sections. 
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Layout handle All SNiFF+ tools consisting of more than one view have a layout handle. The 
layout handle allows modification of the size ratio between two views. By 
dragging the handle with the mouse, the ratio can be changed. 


ae wae 


Browserapplication 


BrowserDocument 


—__._— Click with the mouse and drag 


filebrowser. proj 


| | CONTAINER. proj 
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Common dialogs and windows can be accessed from more than one tool in 
SNiFF-+. 
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Find Dialog The Find/Change dialog is accessible from tools containing text views (like the 
Editor and the Shell) via the “Find/Change...” entry in the Positioning and Edit 
menus. It allows finding and changing with regular expressions (see 
Appendix B). If the text is read only, a Find dialog is opened that does not allow 
changing text. 


Text fields 
Find Describes the text that is to be found. It may contain 
regular expressions. 
Change Is the text that replaces a match on a change command. 
Direction 
Forward / Is the search direction. The start of search is always the 
Backward current cursor position. 
Options 
Ignore Case Specifies either a case sensitive or a case insensitive search. 
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Change Scope 
Match Whole Specifies whether the search string must match a whole 
Word word. The default is that the search string is not restricted 
to being a whole word. 
All of Document/ Only specifies whether the scope of the search is the whole 
Selection document or the currently active selection (default is always 
the whole document). 
Buttons 
Find Next Triggers the search for the next match. | 
Change, Then Replaces the current selection with the change string, then 
Find starts a new search. 
Change All Changes all occurrences of the find string in the current 
change scope to the text entered in the change field. 
Close Closes the Find/Change dialog. 
File Dialog The File dialog is opened on save, new, and open file operations. 


icons 
show the 


file type 


[4 license file 
(postscript 
[4 Version 


— Directory pop-up 
allows movement up in hierarchy 


seceencntannnne ---- List of files 
Pressing a letter on the keyboard positions the list at 
the first entry whose name starts with that letter. 
The up/down keys also scroll the list 


- Editable text field 
metacharacters are expanded with the C-shell 


The text field expands C-shell metacharacters like '~' and $variables. Pressing 
<Enter> in the text field selects the Open button. 
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Files menu 


Directories menu 


Options menu 


Directory pop-up 


Buttons 
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The Files menu lists the most recently opened files. Choosing a file from the list 
performs an open of the selected file and closes the File dialog. 


Permanent entry (retains until explicitly removed) 


Normal entry 


The Directories menu lists the most recently active directories. Choosing an 
entry from the list updates the directory. 


The Options menu serves to configure entries for the Files and Directories menu 
and allows creation of a new directory. 


Configure Files Opens a new dialog that allows making entries in the Files 
menu permanent. Permanent entries stay there all the 
time, regardless of how often they are selected. 


Configure See “Configure Files” above. 
Directories 


Create Directory Creates directory in the current directory. This entry is only 
directory enabled if the name of the new directory is entered in the 
editable text field. 


The Directory pop-up shows the parent directories of the current directory. 
Clicking on it allows fast navigation in the directory tree. 


Open ~ Opens the selected file and closes the File dialog. 
Cancel Closes the File dialog without any further action. 
Update Updates the file list (which is useful when new files are 


created or deleted while the File dialog is open). 


PRELIMINARY TALIGENT CONFIDENTIAL: REGISTERED INFORMATION TALIGENT TOOLS FOR AIX 


173 


174 CHAPTER 12 BASIC ELEMENTS 
COMMON DIALOGS AND WINDOWS 


Peart POLL OP OL ELLE ELLE LEE LL LOTTE OTOL ELLE LECCE TT EEE L EPCOT LEE EL ECOL EO TELL OE CETTE OME AL EET EEG 


Directory Dialog The Directory dialog is very similar to the File dialog: but allows the selection of a 
directory rather than a file. 


— —.. Directory pop-up 
allows movement up in hierarchy 


—————- List of directories 
Pressing a letter on the keyboard positions the list at 
the first entry whose name starts with that letter. 
The up/down keys also scroll the list. 


__....-. Editable text field 
metacharacters are expanded with the C shell 


The text field expands C-shell metacharacters like '~' and $variables. Pressing 
<Enter> in the text field automatically selects the Open button. 


Directories menu The Directories menu lists the most recently active directories. Choosing an 
entry from the list selects that directory and closes the Directory dialog. 


Options menu The Options menu serves to configure entries for the Directories menu and 
allows creation of a new directory. 


Configure Opens a new dialog that allows making entries in the 
Directories menu permanent. Permanent entries stay there 
all the time, regardless of how often they are selected. 


Create Directory Creates dzrectory in the current directory. This entry is only 
directory enabled if the name of the new directory is entered in the 
editable text field. 
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Directory pop-up The Directory pop-up shows the parent directories of the current directory. 


Buttons 


PRELIMINARY 


Clicking on it allows fast navigation in the directory tree. 


Open opens the selected directory and displays its contents in the 
directory list | 

Select chooses the selected directory and closes the Directory 
dialog. 

Cancel ~ Closes the Directory dialog without any further action. 

Update updates the file list (which is useful when new files are 


created or deleted while the Directory dialog is open). 


The Print dialog is opened on print requests from the Hierarchy Browser and the 
Editor. It allows specification of printing options. 


_ Apply current settings 
~ Print to the printer specified below 
A File dialog is opened 


~ Close the Print dialog 


Show page © 
breaks in 
the view 
Range of pages to print 
Paper orientation 
Postscript 
header ; 
Paper size 
(must p 
always bet Scaling factor (range 25% to 400%) 
Set) _ Printer 


ECL EEE EL EET TTL ETE LEELA EEE EELE TELE ELL ELL ERE ERTL EEE EEE ETC A ELLE LEE OEE EE ET 
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The About dialog shows the version number of SNiFF+, copyright information, 
credits, and how to reach the authors. 
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License dialog The License dialog displays information about the floating license server. The 
dialog can be opened by choosing “Licenses...” from the Icon menu. The dialog 
is automatically opened when there is a problem connecting to the license server 
process. A license is only allocated when a project is open. 


dee -.... Area where reason for a problem is 


printed 
Server Rey: <Surg0dech2l > 
Product: <SNiFF+1. 0> vee ae License info “em 
Key: <dgl00a72a2> shows information about the license 
Expiration: sunlimited> server and the currently active licenses 


Maximum Users: <unlimited> 
Current Users: <1: 
sniffasunsb3 (pid=5279} since Wed Dec 2 06:34:59 


- Updates the license info view 
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Progress Window The Progress window appears whenever SNiFF+ needs some time to complete an 
operation. Examples are loading and closing of projects and retrieving a string in 
the Retriever. 


‘Pp 


Pressing the Stop button opens a dialog that allows stopping of the running 
operation. Some operations are not cancelable. 
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The Error log window displays SNiFF+ error and control messages. No messages 
are printed to the terminal where sniff is started. The window can be opened by 
choosing “Error Log...” from the Icon menu. 


resdiff error: , fchri ch file or directory 


ris/. 
co error: revision 1.1 alre 
sniff: cannot dump symbols to directory /usr/openwin/include/X11/. sniffdir 


The Icon menu groups together frequently used commands that have global 
character. 
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Hide Project 


Close Tool 
Hierarchy Browser 
Project Editor 


Documentation 
Browser 


Retriever 
Shell 


Symbol Browser 


Preferences... 
Licenses... 


Error Log... 


_ Application 


Window 


About SNiFF+... 


Quit 


Hides the windows of all tools belonging to the 
corresponding project. This is useful to avoid screen 
cluttering while working with more than one project or 
with several tools. A hidden project can be shown with the 
Workspace Manager (see “Workspace manager” on page 
185). 


Closes the corresponding tool. 


Brings a reusable Hierarchy Browser to the top of the 
display or opens a new tool if no reusable Hierarchy 
Browser is available. 


Brings a reusable Project Editor to the top of the display or 
opens a new tool if no reusable Project Editor is available. 


Brings a reusable Documentation Browser to the top of the 
display or opens a new tool if no reusable Documentation 
Browser is available. 


Brings a reusable Retriever to the top of the display or 


- Opens a new tool if no reusable Retriever is available. 


Brings a reusable Shell to the top of the display or opens a 
new tool if no reusable Shell is available. 


Brings a reusable Symbol Browser to the top of the display 
or opens a new tool if no reusable Symbol Browser is 
available. 


Opens the Preferences dialog to edit user-specific settings 
(see “Preferences” on page 231). 


Opens the License dialog, which shows information about 
the current license status of SNiFF+. 


Opens the Error log window, which shows all SNiFF+ errors 
and other logging messages (see “Error log window” on 
page 177). 

Brings the Workspace Manager to the top of the display. 
This command is useful when the Workspace Manager is 
hidden below other windows. 


Opens the About dialog, which gives information about 
copyrights and how to reach the authors. 


Terminates the current SNiFF+ session. 
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Info menu 


PRELIMINARY 


The Info menu groups together commands for obtaining information about the 


current selection. 


Edit Definition 


Edit 
Implementation 


Retrieve selection 


Retrieve selection 
From Current 
Project 


Retrieve selection 
From All Projects 


Find Symbols 
Matching 
selection or 


Loads the definition of the selected symbol (e.g., a class or 
an enumeration) into an Editor. The mouse shortcut for 
this command is a double click on the symbol. 


Loads the implementation of the selected method into an 
Editor. This command is only enabled if a method is 
selected for which an implementation exists. 


Opens a Retriever and retrieves all occurrences of selection 
from the currently selected projects only (see “Retriever” 
on page 210). 

Opens a Retriever and retrieves all occurrences of selection 
from the root project only (see “Retriever” on page 210). 


Opens a Retriever and retrieves all occurrences of selection 
from all projects (see “Retriever” on page 210). 
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Find Symbols 
Containing 
selection 


Copy Selected 
String 


Show 
Documentation of 
selection 


Serves to get information about all symbols with the current 
selection as name or as part of the name. Both commands 
obtain a Symbol Browser and start the corresponding query 
(see “Symbol browser” on page 204). 


Is enabled for browsing tools. It corresponds to the Copy 
command of text-based tools and copies the string of the 
selection to the clipboard. 


Obtains a Documentation Browser with the documentation 
of the selected symbol (see “Documentation Browser” on 
page 224). This entry is enabled only if there is 
documentation for selection. 


LEP EL LEE LELELEE LE LOTTE LEE ELLE LTTE LE LOL OLE LECCE L OLE ETE EEL ELLE 


The Class menu serves to issue commands for obtaining further class-specific 
information about the current selection (the entries are only enabled if the 


selection is a class). 


Browse Class class 


Show class in 
Hierarchy or 


Show class in 
Restricted 
Hierarchy 


Mark Classes 
Defining method 
or 


Mark Related 
Classes Defining 
method 
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Loads class into a Class Browser (see “Class browser” on 
page 206). 


Obtains a Hierarchy Browser and loads either the entire 
class graph or the graph of the base and derived classes. 
The selected class is highlighted in the Hierarchy Browser 
(see “Hierarchy browser” on page 208). ! | 


Obtains a Hierarchy Browser and loads either the entire 
class graph or the graph consisting of the selected class and 
its base and derived classes. All classes defining method are 
marked in the Hierarchy Browser (see “Hierarchy browser” 
on page 208). 
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History menu 


PRELIMINARY 


There are two possibilities to restrict the amount of information in SNiFF+ tools 
_ that display information in a list (i.e., the Symbol Browser, the Class Browser, and 
the Retriever). 


It is possible to define a regular expression which filters the list via the “Set 
Filter...” command. 


Set Filter... Opens a filter panel that prompts for a regular expression 
filter (see “GNU Regular Expressions” on page 257). 


Reset Filter Resets the filter to allow all entries. 


The list can be further restricted by means of the contents of the view at the 
bottom, which shows either the inheritance graph in the case of a Class Browser 
or the project tree in all other cases. If a project/class has a checked checkbox in 
front of it, its corresponding information is displayed in the list. 


Which information is displayed can be determined either by clicking on the 
checkboxes directly or by setting them via the Filter menu. 


Select From class/ Only displays entries in the list belonging to the class/project 
project selected in the project tree. 


Select From All Displays entries from all classes/projects. 
Classes/Projects 


The History menu serves to reset the tool to a previous state (or to issue an 
earlier query again). The structure of the entries depends on the kind of tool 
from which the menu is invoked. 


The number of queries to be remembered can be specified in the Preferences 
dialog (see “Preferences” on page 231). 
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The Edit pop-up menu appears when the right mouse button is pressed in any 
editable text item or in a text view. 


Undo command — Undoes the last change (command) to the text. The number 
of remembered undoable commands can be specified in 
the preferences file (see “ETRC file entries” on page 261). 


Redocommand __ Redoes the last undone change (command). 


Cut Cuts out the current selection into the paste buffer. The 
entry is only enabled if there is an active selection. 


Copy Copies the current selection into the paste buffer. The 
entry is only enabled if there is an active selection. 


Paste Pastes the contents of the paste buffer at the current cursor 
location. If there is an active selection, the selection is 
replaced by the pasted text. The entry is only enabled if the 
paste buffer is not empty. 


“2NOTE The Undo, Redo, Cut, Copy, and Paste commands are also accessible 
from the Edit pull-down menu in tools like the Editor and the Shell. 
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Keyboard shortcuts The complete functionality of SNiFF+ is provided via the menus of the various 
tools. To speed up the work, especially for experienced users, SNiFF+ also 
provides three different types of shortcuts to allow faster access to the commands 
found in menus. 


Keyboard shortcuts are issued by holding down <Alt> of your keyboard and 
pressing the key that is shown at the right of a menu entry. Some frequently 
used shortcuts are: 


« <Alt>C for copy 
« <Alt>V for paste 
« <Alt>B for browse class 
Mouse shortcuts are issued by double-clicking with the mouse on entries in 
lists or on selectable items. Some frequently used shortcuts are: 
# Editing the source of a symbol by double-clicking on it in the Symbol 
Browser 


« Jumping to the source location of a variable by double-clicking on it in 
the Class Browser 


Deep clicks are issued by holding down the <Ctrl> key and pressing the left 
mouse button. Some frequently used deep clicks are: 


# Switching from the declaration of a symbol to its implementation by 
<Ctrl>clicking on the symbol in the symbol list of the Editor 


Restricting the information shown in the list of a Symbol Browser by 
<Ctrl>clicking on the checkbox of a project in the project tree view 


# Showing methods of only one class in the Class Browser by <Ctrl>clicking 
on the class in the inheritance graph view 


Fast positioning Pressing an alphabetical key while the mouse pointer resides over a list will 
in lists position the list to the first entry whose name starts with that letter. 
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WORKSPACE MANAGER 


The Workspace Manager serves to manage projects and open tools. It consists of 
a menu bar and a list of open projects. Cee 


Icon 


Menu bar Seat Beck 
menu ane a 


.proj 
ilehrowser. proj = Open project (windows of project are visible) 


nerviews proj |__------- Hidden project (all windows of project are hidden) 


List of loaded projects 


Commands in the list of 
loaded projects 


Double-click On a loaded project hides/shows all windows belonging to 
that project. This command is also available via the Icon 
menu. 

<Ctrl> On a project shows the windows of that project and hides 

click the windows of all the other projects. 
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The Project menu serves to create new, open existing, and close open projects, as 
. well as to quit SNiFF+. For a description of project files see “Project file” on page 


239. 


New... Opens a Directory dialog, which prompts for the directory 
where the source files of the new project are located. After 
the directory has been specified, a Project Editor is opened 
asking whether to load all existing C/C++ files. The newly 
created project has to be stored in a project file. 


source files directory can contain environment variables. Selecting directories 
with the browser of the Directory dialog always stores the absolute directory path 
into the project file. Entering the complete directory specification in the text 
field at once retains used environmental variables and other shell metacharacters 
like ‘~’. To change the source path of a project after it is created, see “Project 
Attributes Dialog” on page 199. | 


Open... Opens a File dialog, which prompts for an existing project 
file. After a project file has been specified, the project is 
loaded into SNiFF+ and the environment (all window 
positions, sizes and contents) is restored to the same status 
as when the project was closed the last time. 


Close project Closes the selected project and all windows belonging to it. If 
the structure of the project has been modified, a panel is 
opened asking whether the project file should be saved. On 
a reopen, the project environment is restored to the same 
status as when the project was closed. 
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PROJECT EDITOR 


The Project Editor is used to edit and browse project-specific information: 
« Project attributes 
« Information about which files belong to the project 
« Subprojects 
« Version control and locking information. 


“£ NOTE While the Project Editor serves to browse the entire tree of projects 
that are loaded, only the structure of the root project can be edited. To change 
the structure of a subproject, it has to be opened as a root project itself. 


The Project Editor stores the project information in project files (see“SNiFF+ 
projects” on page 244). 

A Project Editor can be opened by choosing “Project Editor” from the Icon 
menu. 

A Project Editor contains two views. The upper view displays a list of files and the 


lower view shows the project tree. The amount of information shown in the list of 
files can be controlled with the Filter menu (see “Filter menu” on page 181). 


Icon -—— 
menu ee Regular expression filter currently allowing all files 
---. Pressing the button shows locking and version 
control information 
AccessMem. 6 
AccessMem. h 
Alert.C 
acc: | come List of files 
, ©. 5 " A . 
Application. ¢ determined by project tree settings and filter 
application. h 
Backgrounditem. C 
BackgroundItem. h 
Bitmap. C 
Bitmap. h 
sme -—-—— Layout Handle 
ae ; allows modification of size ratio between the two views 
Project is Root project 2 
writable eciral et. proj ; Subproject 
ee le ][teelly’] CONTAINER. proj 
fae | __ Subproject of subproject — project tree 
ibrary (no 
Vn eee showing the project structure 
Show files in file list , 
writable) | and the attributes 
———--- Don't link objects to target : 
Tool is ~ 
reusable 
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ile list The list of files shows the files belonging to the root project and its subprojects. 
| The list is restricted by the setting of the project tree (checkboxes) and by the 
filter. | 
Project tree The project tree shows the hierarchical project structure including all 


subprojects. It also shows whether the project is writable and whether its objects 
should be linked to the project target of the root project. The attributes 
displayed in the project tree can be edited in the Project Attributes dialog (see 


below). 
. - | 
Es 
| po po 
Project is a library; Projectis read-only; Project is writable — Link objects of Don’t link objects of 
project attributes neither attributes Project to target Project to target 


may be modified but nor source files may 
not the source files be modified 


The checkbox of the project defines whether the files of the project are shown in 
the file list. They can be modified directly with the mouse or can be set by the 
Filter menu. | : 


A deep click (<Ctrl>click) on a project entry (not on the checkbox) selects only 
files from that project and hides all others. | 
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File menu The Project Editor's File menu serves to issue commands that create, open, and 
save projects, as well as to quit SNiFF+. For a description of project files see 
“Project file” on page 230. 
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New Project... 


Open Project... 

Close Project The same entries as in the Project menu of the Workspace 
Manager. 

Save Project Saves the project file (this entry is only enabled if the 
project structure or attributes have been modified since the 
last save). 


Save Project As... Opens a File dialog, which prompts for the new project file 
name. 
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The make menu serves to issue make commands. The command actually issued 
by these can be specified in the Preferences dialog and in the Project Attributes 
dialog (see “Project Editor” on page 187). 


Make File Obtains a Shell and starts “make objectfile’ in the project's 

objectfile source directory. 

Make target Obtains a Shell and starts “make target” or “make project’, 

target or Make respectively, depending on whether the selected project has 

Project project a defined target, in the project's source directory. If no 
project is selected in the project tree, the root project is 
taken. 


Recursively Make Obtains a Shell and starts the “make” command for all 

target or Make All writable subprojects. Finally, “make target” (or only “make” 

Writable Projects if the root project doesn't have a defined target) is called 
for the current root project. 


Update Makefiles Updates the dependency information for the makefiles of 
all writable projects. This command has to be issued only 
when a new include statement is inserted in one of the 
source files of the project. This command need not be 
issued when attributes or the project structure are changed, 
in which case SNiFF+ updates the makefile information 
automatically. 
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The Project menu serves to issue commands that manipulate the attributes and 


structure of the current project. It is not possible to change information defined 
in a subproject. To change a subproject, it has to be opened as a root project on 


its Own. 


Source Files... 


Load Subproject... 


Unload Subproject 


Attributes of 
Project project... 


Force Reparse of 
project 


Update Symbol 
Table of project 
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Opens the Source Files dialog that serves to define the 
project's source files (see “Source Files dialog” on page 
197). 

Pops up a File dialog box which prompts for the project file 
of a subproject to be added. It is only possible to load 
subprojects for the root project. If a subproject is to be 
added to a subproject, it has to be opened as a root project 
on its own. 


Purges the selected subproject from the current project. 
This command is only enabled for subprojects of the root 
project. 


Opens the Project Attributes dialog described on page 199. 


Perfoms a reparse of the selected project. A reparse is 
necessary, e.g., if the parser configuration file has been 
modified (see “Dealing with preprocessor macros” on page 
226). 


Checks for all files belonging to project if the corresponding 
source files were changed since the symbols were loaded 
and reparses only the modified files. This command has to 
be executed only if project files were modified with tools 
other than SNiFF+ (see “Editor” on page 213). 
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Dump/Remove Dumps or removes a project-specific symbol table 
Symbol Table of | containing the symbolic information about the whole 
project project. This entry is only enabled if the project is a library 


project. Further explications can be found in “Tuning and 
persistency of symbolic information” on page 243. 


Delete Symbol files Deletes all symbol files of this project. Symbol file 
management is normally fully transparent to the user. This 
command is necessary only if the symbol files have a wrong 
modification date (due to a copy or some other reason) or 
were corrupted. On a project close then, new symbol files 
will automatically be created. 


Print Statistics Displays the number of symbols, files, and included files for 
every project, as well as a summary of all projects, toa 
reusable Shell. 

Show Locking button Pressing the Show Locking button shows locking and version control 


information in the Project Editor. 
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Project Editor with When the Project Editor is opened for the first time, locking and version 


locking information information is hidden. After the Show Locking button is pressed the Project 
shown Editor displays also locking and version information for the selected projects. For 


a general discussion of the integration of version control systems in SNiFF+, see 
“Version control” on page 254. 


sa eee List allows multiple selections. 
' ae A selection can be extended by pressing <SHIFT> 
ProjParamsDiag.h : ‘ ; ‘ 
ProjTextItem, ¢ ete 46 : and selecting entries. All entries of a list can be 

te wal selected by pressing the “Select All” button. 


ProjTree¥View. C 


ProjTreeView.h Type of the version control system 
RecsAdaptor. C 


Recsédaptor.h 

Retriever. ¢ joe: 1. Bde Locker(s) and locked version(s) 

Retriever.h- 

File status, source file name and project name 


SH1FF+ eT . 
iia Pow Cua ieee peeeeae wee nen Ieee Descriptive text of the selected source file can 


be changed with the “Change” button 


History of the selected source file 


author: gil; 
. enum, enum items inside a class. 


: 1993/06/11 13:89:23; author: 


Revision number for check in, check out and 
unlock operations 


EM || Slly’| sniffeditor 
PAX| | communication 


pA[H][_ |] stringmanager 
| aamtah 
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File list and status line The file list is a multiple selection list and displays the following information: 


Name of the file —_Is the same as in the Project Editor without the locking 


information. 
Underlying Is the type of the version control system used. The following 
version control systems are currently supported: RCS, SCCS, SNiFF and 
system none if no version control system is used. Different version 


control systems can be used for different projects. The 
Project Attributes dialog (see “Project Attributes Dialog” on 
page 199) determines which version control system is used. 


User name of Is only displayed if the file is locked by somebody. 
locker and locked | 
version 


The status line displays the state of the file, the filename and the project name it 
belongs to. 


The modification state icon is determined by comparing the working file with the 
version file and can be one of these: 


Working file is not Working file is writable | Working file and last checked in version differ. Either the working file is 


writable and not and not modified modified or a new version has been checked in by somebody else 
modified , 


The icon can be empty if the file has never been checked into the version system. 
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Locking menu 


The Locking menu is only visible if the Project Editor shows locking information. 


Hide Locking 


Check Out 


Check In... 


Hides the locking information in the Project Editor and 
also hides this menu (same effect as pressing the Hide 
Locking button). 


Checks out the selected file(s). If a valid version number is 
entered in the Revision text field (see below), this version is 
checked out, else the latest version is checked out. If 
multiple files are selected, the latest versions are checked 
out. Depending on the “with lock” button setting, the 
locking of the file is influenced in the following way: 
« With lock (default) the file(s) are 
checked out writable and locked for 
the current user. 
# No lock the file(s) are checked out 
read only and are not locked. 
The “Check Out” menu entry in the SNiFF+ Editor always 
checks out the file with a lock (see “File menu” on page 
188). 
Checks in the currently selected file(s). A Log message 
dialog box is opened, prompting for the log message to be 
saved with the checked in version. The log messages for the 
various versions of a file are displayed in the History text. 


If a valid version number is entered in the Revision text 


field (see below), this version is checked in, else a new 


version in the current branch is checked in. If multiple files 
are selected, the latest version of the currently locked 
branch is checked in. If a working file is not modified, a 
dialog asks whether the file should still be checked in. 
Depending on the “with lock” button setting, the locking of 
the file is influenced in the following way: 


# With lock: the file(s) are checked in as 
new version(s) but are still locked for 
the current user and writable. 


TALIGENT TOOLS FOR AIX TALIGENT CONFIDENTIAL: REGISTERED INFORMATION 


PRELIMINARY 


Files popup button 


Unlock 


Update 
Information 


CHAPTER 13. SNIFF+ SUBSYSTEMS 
PROJECT EDITOR 


« No lock (default): the file(s) are 
checked in, the lock of the current 
user is released, and the protections of 
the working source file(s) are set to 
read only. 


The “Check In...” menu entry in the SNiFF+ Editor always 
checks in the file and removes the lock (see “File menu” on 


page 188). 


Removes the lock from the selected file(s) and sets the 
protection of the working source file(s) to read only. The 
version file(s) in the version control systems return to the 
same state they had before the lock was set. If the working 
file is modified, a dialog asks whether the lock should be 
removed. The Unlock entry is only enabled if the selected 
file is locked. A revision number can be entered to cover 
the case that several revisions are locked on different 


_ branches. 


Updates the information of all files displayed in the file list. 


The files popup button is used to constrain the list of displayed files. 


all 
modified 


Own 


own modified 


Displays all files regardless of the locking state. 


Displays only working files that are different compared to 
the last checked in version. There can be two reasons for 
that: 


# The working file is modified by the 


current user 


# A new version has been checked in by 
someone else and the working file is 
out of date. : 


Displays only files that are locked by the current user. 


Displays only files that are locked by the current user and 
are modified. 
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Description text 


History text 


Check Out button 
Check In button 
| Unlock button 


Revision text field 


-~$CCS only: New Branch 
button 


The Description text displays the description for the selected file. It also serves to 
enter the description for a newly checked-in file. The text can be of arbitrary 


length and may contain new-line characters. The description text can be 


changed and stored with the “Change” button and with single-file check-ins. 


The History text shows the log entries for the checked-in versions. Most recent 
entries are displayed at the top, old entries at the bottom. RCS symbolic names 
are displayed at the very bottom. 


The Check Out button has the same effect as choosing “Check Out” from the 
Locking menu. 


The Check In button has the same effect as choosing “Check In...” from the 
Locking menu. 


The Unlock button has the same effect as choosing “Unlock...” from the Locking 
menu. 


This field is used for check in, check out, and unlock operations and determines 
what version of the selected file is checked in/out. If the field is empty, the latest 
version of the file is taken. 


When SCCS is the version control system, a new button appears above the 
Revision text field: 


Only visible when SCCS is used 


The New Branch button allows the creation of new branches during SCCS check- 
out operations. 
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Source Files dialog The Source Files dialog serves to handle the source files of a project. It is opened 
by choosing “Source Files...” from the Project menu. 


Project directory 


ET++.h 

ET Begin. h 
Na iy gta BS ot 
RSE Na eos Re Rees 
ET Redefin 
ET Undefaine 


qapplication. h 
iBackqroundI tem. C 
{BackgroundI ten. h 
(Bitmap. 0 
{Bitmap.h 
{Bitset.¢ 
jbitset. h : : 
eer | a foe | een List of files 
with multiple selections possible. 
A selection can be extended by pressing 
1g <SHIFT> and selecting entries. All entries 
Buttons. h ’ : 
ipeteie ee of a list can be selected by pressing the 
jBytearray.h “All” button 
qChangeDialog. C 
dChangeDialog.h 
jCheapText. C 
CheapText.h 
Class.C 
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Buttons 
All 
Unload 


Create 


Load 


Rename 


Delete 
Update 


Done 
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Selects all elements in the list. 


Unloads the selected source file(s) from the current 
project. All symbols of an unloaded file are removed from 
the project. This command is only enabled for files of the 


root project. A file can also be unloaded by double-clicking. 


Pops up a dialog box, which prompts for the name of a 
source file to be created and loaded. The file name must 
have one of the legal extensions for include or 
implementation files. (Legal extensions can be specified 
with the Preferences dialog as described in“Preferences” on 
page 231.) Ifa legal filename was specified, no file with the 
indicated name exists, and access permission allows the 
creation of the file, then it is created and filled with a 
template. A template name starts with the string “template.” 
and has the same extension as the newly created file. User- 
specific templates can be provided by storing them ina 
directory that is specified in the Preferences dialog. Site- 
specific templates are stored in the config directory of the 
SNiFF+ installation directory (see “Preferences” on page 
231). If no templates are provided, then an empty file is 
created. | 


Loads the selected source file(s) into the project. To load a 
file into a project means to parse the file and load the 
symbolic information. A file can also be loaded by double- 
clicking. 

Pops up a dialog box, which prompts for the new name of 
the file. Only files in the directory can be renamed. To 
rename the file of a project, unload the file, rename it and 


load it again. The button is only enabled if a file is selected. 


Deletes the selected file(s) if file permission allows. SNiFF+ 
asks for confirmation before actually deleting the file(s). 


Updates the lists of file, which is necessary, e.g., if a new file 
is created in the shell. 


Closes the Source Files dialog. 
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Project Attributes Project specific parameters are edited with the Project Attributes dialog and are 
Dialog stored in the project file. Some of the parameters override user preference 
settings (see “Preferences” on page 231). 


Changes to the project attributes take immediate effect if not otherwise specified 
in the text below. Attributes of frozen projects cannot be changed. 


The following picture shows the Project Attributes dialog for a root project. 
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Target 


Source Path 


Tab Width 


Generate Dir 
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Defines the name of the target of a project. The target 
name is used to drive the make command and the 
Debugger. | 


Specifies the directory where the source files of a project 
are located. In the standard case this path is set 
automatically when the project is created and is never 
changed. 


The reason for changing the Source Path attribute is to 
improve the transportability of a project. If a project has to 
be transported to another place in the UNIX directory tree, 
two problems occur. First, the source files cannot be found 
anymore because the absolute path name of the source 
directory is stored in the project file. Second, the project 
cannot be compiled because the path names of generated 
makefile parts are outdated. The first problem is solved by 
asking the user for the new source directory path when the 
source files cannot be found anymore in opening a 
project. The second problem can be solved by updating the 
make support files manually (see “Make menu” on page 
180). 


A general way to enhance transportability of projects is to 
use environment variables as part of the source path 
specification. This also allows project team members to 
work on the same project but on different NFS mount 
points in a network. 


Is used to specify the length of the spacing between two tab 
stops. The default width is set in the Preferences dialog (see 
“Preferences” on page 231). 


Indicates the directory where SNiFF+ puts the project- 
specific files generated for this project (see “Files created 
and used by SNiFF+” on page 239). Per default a directory 
.sniffdir is created in the source directory of the project. 
You may want to change the directory if you are not allowed 
to create a subdirectory in the source directory of the 
project. SNiFF+ displays a warning message in the Error log 
if permissions prevent writing to the generate directory. 


TALIGENT CONFIDENTIAL: REGISTERED INFORMATION 


PRELIMINARY 


CHAPTER 13 SNIFF+ SUBSYSTEMS 201 
PROJECT EDITOR 


Parser Config File Indicates the file where special configurations for the 
information extractor are stored (see “Files created and 
used by SNiFF+” on page 239). If a new parser 
configuration file is specified, or an existing file has been 
changed, SNiFF+ has to reparse the source file(s) with the 
changed configuration. Reparsing can be forced by issuing 
“Force Reparse” from the Project menu. Effect of the 
change: Reparse of the project. 


Make Command _ Specifies the command to be submitted to the Shell when a 
make command is issued (see “Make menu” on page 189). 
The default is set in the Preferences dialog (see 
“Preferences” on page 231). If you compile on a compile 
server, you can change the command, for example, to “on 
server make”, or you can provide your own shell script to do 
fancier things. 


Class Prefix Is used only in conjunction with debugging. To enhance 
integrability with other software systems, class libraries 
sometimes add a prefix to classes with a macro. This prefix 
change is not visible to SNiFF+ since the information 
extractor does not do macro expansion. To allow 
transparent symbol matching between browsing and 
debugging, the class prefix attribute may be set. ET++, for 
instance, uses the class prefix 'ET_' for all of its classes. 


Makefile Support Specifies whether the support files (ofiles.incl and 
dependency.incl) for the makefile are generated (see 
“Makefile Support” on page 249). 


Overlay Files Specifies whether files of subprojects should be overlaid by 
files with the same name of superprojects. If this option is 
set in the sub- and superproject, SNiFF+ hides the symbols 
of files which are overlaid. This feature enhances the 
teamwork support (see “Teamwork Support” on page 234). 
If this option is switched off, all files are loaded, even if two 
of them have the same name. Default is not to overlay files. 
Change takes effect on the next project open. 
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Locking Parameters 
Tool 


Path 


determines which version control system is used for the 
project. 


A description of the integration of the different tools can 
be found in “Version control” on page 254. SNiFF locking 
is a simple SNiFF+ internal locking but without the version 
control features of the other supported tools. 


Defines the path where SNiFF+ searches for the version tool 
subdirectories. The default path is the source directory of 
the project. The path specification must not contain the 
directory name of the version control system. The following 
directories are added to the path for the various version 
systems: 


Version control Directory 
system 

RCS RCS 
SCCS | SCCS 


If the directory of the version control system is not located 
in the source directory of the project, no link to the actual 
version control directory is needed. Just enter the path 
where the version control directory is located. Several 
SNiFF+ projects can share one common version control 
directory. 
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Project parameters 


Project is Library Specifies whether the project is a library project. Library 
projects are frozen and cannot be modified. This 
information is also shown in the project tree of the Project 
Editor (see “Project Editor” on page 187). 


Link Objects of Specifies whether object files of the project have to be 


Project linked to the target. This information is also shown in the 
project tree of the Project Editor (see “Project Editor” on 
page 187). 
Project Attributes Attributes of frozen subprojects cannot be changed. Only the “Project 
dialog for frozen Parameters” can be overridden if the overriding results in a restriction. E.g., an 
subprojects editable subproject can be frozen, but a frozen subproject cannot be turned 


editable. If project files are to be linked, this can be turned off, but not vice versa. 


If the attributes of a frozen subproject have to be changed the project must be 
opened as a root project and must be unfrozen. 
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The Symbol Browser consists of a list of symbols whose content is determined by 
the type pop-up menu, the project tree settings, and the filter field. The type 
pop-up menu allows selection among C++ constructs such as classes, methods, 
and variables, as well as preprocessor macros. The project tree shows the project 
structure and makes it possible to select the projects whose symbols are displayed. 


Symbol Browsers are obtained by issuing the “Symbol Browser” command in the 
Icon menu. The other way to obtain a Symbol Browser is to issue a “Find Symbols 
Matching selection” or a “Find Symbols Containing selection” command from the 
Info menu. In this case they show a symbol list that is filtered by selection. 


Icon 
menu 
Regular filter expression (currently allowing all symbols) 
Type pop-up 
BackgroundI tem 
hatchInfo (struct: WindowPort.h 
List of Symbols 
determined by type pop-up menu, filter, and project tree 
settings 
ro Double-clicking on a symbol loads the source code 
into an Editor 
BrowserDocument eee Layout handle 
ee allows modification of the size ratio between the two views 
Defines ae ilebrowser. proj 
whether | Yet. proj Project tree 
symbols [| CONTAINER. proj showing the project structure 
are listed 
Filter also matches part of a word 
Tool is 
reusable 


Abstract classes (i.e. classes that define a pure virtual method) are displayed in 
italic font face. 
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C structures and unions as well as typedefs for structures and unions are listed as 
class types, whereby the names of these types are marked as “(struct)” or 
“(union)” in the symbol list. C++ templates are also listed as classes, whereby the 
names of the templates are followed by “(template)”. 


The list of methods and instance variables can get very long, since they are flat 
views of all methods/variables in the project. Symbols of the same type with the 
same name are qualified by the name of the file they belong to. 


PPMP PLP LLL OEPL ALP LPP EPI SILOPPEPLL EL: 


The project tree shows the hierarchical project structure including subprojects. 
The only symbols shown are those whose project checkbox is checked. The 
checkboxes can be manipulated directly with the mouse or can be set with the 
Filter menu. A deep click (<Ctrl>click) on a project entry (not on the checkbox) 
will list symbols only from that project and will hide the symbols of all other 
projects. 
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CLASS BROWSER 


The Class Browser shows a list of local symbols of the class currently being 
browsed. The content of this list is determined by the type selector, the settings of 
the inheritance graph view, and the filter field. The type selector is a pop-up 
menu that allows selection among methods, instance variables, local types, local 
enumerations, and friends. Class Browsers are invoked with the “Browse Class 
class’ command from the Class menu. 


The access privileges of methods and instance variables are indicated by the color 
of the squares located in front of them. Black means private, gray means 
protected, and white means public. 


Icon 
menu -- Name of class being browsed 
- Regular filter expression (currently allowing all symbols) 
Type pop-up 
[_] Button Button 
[] DoLeftButtonDowce Button 
[] DoTrackMouse Button 
[] DrawHighlight Button 
Visibility [] Flush Button 
white: C] GetMinSize Button 
public [] SetLabel Button . 
gray: CO setorigin Button oo gee List of local symbols (symbol name and class name) 
protected determined by type pop-up menu, filter, and inheritance graph 
black: settings; 
private a double-click on a symbol loads the source code into an Editor 
Layout handle 
allows modification of the size ratio between the two views 
Defines 
whether a eae h 
inheritance gra 
symbols | | ComposrtevOhject howina th g it th with all 
are listed  vabject showing the inheritance path with all superclasses 
| | ivizendier — 
Tool is | object | | 
reusable All symbols are shown, including overridden ones 
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Type pop-up 
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The inheritance graph view shows the graph consisting of the browsed class and 
its superclasses. The checkboxes in front of the classes show whether elements of 
those classes are listed. The checkboxes can be manipulated directly with the 
mouse or can be set with the Filter menu. A deep click (<Ctrl>click) on a class 
entry (not on the checkbox itself) will list elements of that class only and will hide 
the elements of all other classes. 


PEBBLE LEELA IEDR LEO E LEB EO E ODES ADE EQ CDSE OOOO ELE OE OLAS AEA CEA EOD LILO E BOO O OO GO On 


A further filtering mechanism is the possibility to hide overridden methods. This 
option can be set with the “Hide overridden” toggle button in the status line. 


The type pop-up specifies the type of the class elements shown in the list. 
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The Hierarchy Browser is a graph browser designed to visualize a class graph. It 
either displays the entire class graph or only the superclasses and subclasses of 
the class indicated in the title of the browser view. | 


Hierarchy Browsers are invoked with the “Show Class in (Restricted) Hierarchy’, 
or the “Mark (Restricted) Classes Defining Method method’ command in the 
Class menu. Another way is to issue “Hierarchy Browser” in the Icon menu. 


There are two ways to mark a subset of the displayed classes. One way is to mark 
all classes that define a certain method. This kind of marking is obtained by 
issuing the “Mark (Restricted) Classes Defining Method method” command in the 
Class menu. The other way is to issue the “Mark Documented” command in the 
Info menu of the Hierarchy Browser. 


The semantics of the current marking are described in the status line. 


Icon 
Menu =——s*“ Bipewchyof Gasses Remtica wih Buiton lt. Scope of view 
/ Scrol]BarButton 
| ActionButton | Inheritance relationship 
y | ittonIten from left to right 
i , Yobj ectButton . Marked Class 
‘Object CompositeVobject fs if - RadioButton (status line shows 
\ stateButton a ToggleButton Sp mnanties) 
------- Normal class not marked 
‘ | Popup. 
\ ueHuButton — Pul 
Nenu! 
Abstract class 
containing pure virtual 
methods 
Tool is Semantics of marking 
reusable = 


Abstract classes (i.e. classes that define a pure virtual method) are displayed in 
italic font face. 
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The Hierarchy menu serves to issue a set of commands related to the Hierarchy 
Browser. 


Edit Method —_ Loads the implementation of the corresponding method of 
method of Class the marked class into an Editor. 

class 

Reset markings Resets the currently active markings. 

Print... Opens a Print dialog for printing. 


PELOSI GOL P OPEL IOSD EOP IOP MPEOS, 


The Projects menu makes it possible to show only classes of certain projects and 
to hide others. Hidden classes in the class graph are represented by a '+' sign. 


Select From All Shows the classes of all projects in the hierarchy view. 
Projects 

Select From No Hides all classes except abstract classes. 

Project 


Project entries with Hides or shows the classes of projects individually. All 
a toggle button Project entries can be manipulated with the “Select From 
All Projects” and “Select From No Project” menu entries. 
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Icon 
menu 


Also 
search this 
project 


Tool is 
reusable 


The Retriever shows a list of matches and a project tree view. The information 
about matches consists of the corresponding source file, the string that was 
matched, and the source line containing the match. The matches are obtained 
by a regular-expression-based search in all source files of the projects marked in 
the project tree view, and filtered with the active filter expression. In other words, 
the Retriever (like a super- grep in UNIX) starts a full text search over the project 
files and issues flexible semantic filtering as a second stage. 


A Retriever is obtained by choosing the “Retrieve...” entries from the Info menu, 
or by issuing “Retriever” from the Icon menu. | 


Search string 


Active filter 
Manager. 0 menu. menu= new Menu(cEDITMENU, "“Edit"); 
Manager. C Menu henv= new Mernu(cEDITMENU, “Edit"); List of matches 
Menu. 0 men. { INenu= mn; exitRect= er; vop= Vv; } filename, 
Menu. h eMenuTitle eMenuTitle BIT (eEvtLast+1}, match, 
Menu. h eMenuNoScroll eMeruNoScroll BIT (eEvtLast+2), source line 
Menu. h eMenuDefault eMenuDefault eMernuTitle, 
Menu. h eMenuLast eMenuLast eEvtLast + 2 
Look. C popUpMenuLayout popUpMenuLayout= menuLineLayout= 0; --- Layout handle 


Look. C menuLineLayout popUpMenuLayout= meruLineLayout= 0; allows 
CmdNo.h cHELPMENU cHELPMENU BO, | 


modification of 
La the size ratio 


between the two 
filebrowser. proj views 
LY et. proj 
| | CONTAINER. proj 
Sa Sane project tree 


i 
Hq 
t 


Case insensitive Also match part of a word Number of matches 


The search process can be triggered either from the Retrieve menu by pressing 
the Retrieve button, or by pressing <Enter> after the regular expression defining 
a query. After the first retrieve, the source code is cached and all further queries 
are much faster. Caching can be switched off in the Preferences dialog (see 
“Preferences” on page 231). A Progress window indicates the progress of the 
search. | 
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{éNOTE The Retriever is the only SNiFF+ tool that is not updated after changes 
are applied to the source code. 
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Project tree 


Retrieve menu 
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The project tree shows the hierarchical project structure including subprojects. 
Only symbols of projects are shown where the checkbox is checked. The 
checkboxes can be manipulated directly with the mouse or can be set with the 
Filter menu. A deep click (<Ctrl>click) on a project entry (not on the checkbox) 
will list symbols only from that project and will hide the symbols of all other 
projects. | 


LLL LP ELIE LEP PLL OLE EL EL EP OEE EAL PPPLL EL ALO ALLEN IL OL LED AOL OIL EOE CIEE LIEN OOOO OD 


Ignore Case Specifies whether the search is case sensitive. The default is 
case sensitive search. 


Match whole word Specifies whether the search string must match a whole 
word. The default is that the search string is not restricted 
to being a whole word. 


Matches Displays the number of matches. 


The Retrieve menu serves to trigger the retrieve process. 


Retrieve selection ‘Triggers retrieving based on the current selections in the 
project tree view. 


Retrieve selection ‘Triggers retrieving from the root project only. 
From The Current 
Project Only 


Retrieve selection ‘Triggers retrieving from all projects. 
From All Projects 
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The Retriever's Filter menu consists of the standard Filter menu described in 
“Filter menu” on page 212 and a set of extendable semantic filters. These 
semantic filters are predefined regular expressions that serve to sensibly restrict 
the number of matches obtained from textual searches. 


Predefined filters are: 


Call Lists only matches where the matched string is a method or 
procedure call. | 

Assignment Lists only matches where the matched string is assigned a 
value. 

Comparison Lists only matches where the matched string is part of a 
comparison. 

New Lists only matches where the matched string is preceeded 
by “new”. 


Additional filters can be added or the four standard filters can be overridden by 
providing a file consisting of a sequence of lines of string pairs delimited by 
double quotes (“”). The first string is added to the menu and the second string is 
the filter which is inserted on selecting the corresponding menu entry. The 
Preferences dialog can be used to tell SNiFF+ where to find the filter extension 
file (see “Preferences” on page 231, “Files created and used by SNiFF+” on page 
239, and “Appendix A. GNU Regular Expressions”). 


In formulating a filter criterion, the string “%s” can be inserted several times. It 
will be expanded with the actual search string. 
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Icon menu 

reflects editing state 
- read-only 

- not modified 

- modified 

currently: r/o 


Symbol names are 
displayed in special 
font faces 


Comments are 
displayed with a 
special font face 


Tool is reusable 


ore Tes 
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SNiFF+ offers two possibilities for editing source code: 
« SNiFF+'s own integrated Editor. 
« An interface to standard Emacs version 19 or later (see “Emacs integration” 
on page 250). 
This section describes how to work with the integrated Editor. 
SNiFF+'s Editor consists of a WYSIWYG text Editor and a list of classes, methods, 
and functions defined in this file. This list speeds up the positioning by 
displaying the source code when a symbol is selected. 
The Editor partially understands C/C++ syntax and can print comments and 
symbols with a different typeface. Which fonts and colors should be used for 
which symbols, the line spacing, and other attributes of the Editor can be defined 
in the ETRC file (see Appendix B, “ETRC File Entries”). 
Besides the standard editing functionality, the Editor provides support for 
copying and moving the selection by direct manipulation, and it selects the text 
between matching characters such as brackets and quotes. 
. public WBox { Class pop-up 
; Lb ecesa SEA A RAS menu either 
SeqCollection *path. +directories; BrowserView (nd shows all 


ClassDecl (md) F 
Control {md} Bro 
CreateFunctionte 
DirectoryNameAt 
DoSetup (md) Bra 
FileBrowserPPrin 
FileBrowserPPrin 
FileBrowserTextv¥ 
FileBrowserTexty¥ 


Compasi even tect *fafelists: ¢ shown frie diate 

int m&fo ’f munder of shorn 
int lett; fs index of left mos 
VObject) *shaftleft, * SRE ICRI GRE; ff dattons 


ChangéDirliag *changeDzr ; 


void LoadFile(int at, FileList *f1); 
void Shellf{int at, char *path, char *cmd= 03; 


one class 


Symbol list 


pop-up menu 


bli ee 
ae (clicking on a 


classes or only 


(current setting) 


defined by class 
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MetaDef (BrowserView) ; 


BrowserView(EvtHandler *dp, int numPilelists); 


~BrowserView(} ; 


respond to see znput 
ae Controlfint id, int detail, void *dataj,; 
bool GrabKeyToken (Token &t) ; 
yoid DoSetup() ; 


ff-~-- directory Aandi rag 
SeqCollection +ReadDirectory () ; 

yoid ShowDirectory(int at, char *name) ; 
oid ShowParentDirect 0; 


{ 
i 
| 
| 
i 
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ReadDirectory (1 
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ResetFunctionMen 
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cursor) 


- Layout Handle 
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When a file is edited, the icon of the Icon menu changes to a warning sign until 
the file is saved. 


| | | 


File is not writable _ File is writable File is modified - 


The entered text is automatically reformatted. The time interval between 
reformatting can be set in the ETRC file (see Appendix B, “ETRC File Entries”). 


OTT T TST R TE TTT eee re, seratatenaa eee neeectceds re 


Symbol List The Symbol List is constrained by the Class pop-up and shows the list of: 


Method declarations “md” and implementations “mi” 
# Class definitions “cl” 
# Functions “f” 
The Editor is positioned at the symbol by clicking on an entry in the Symbol List. 


A deep click (<Ctrl>click) on a declaration entry will position the Editor at the 
implementation and vice versa. 


SaaS PLL PELEPL ILL LLLP LEE SLE EPP LLL IOP ILL OE IPL LD, PIPLLOL?, LPOPLLOLP LPP LILIES PLL IL ELLE ELIS ODPL EEL IIL SPELL ALL ELLE OL LE POL: 


Class pop-up The class pop-up scopes the Symbol List to either show only symbols of one class 
or to show all symbols of this file. This feature eases navigation when there is 


more than one class defined in a file. 
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File menu The Editor's File menu contains standard commands for loading and saving files. 
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Load... 


Save 


Save As... 


Revert 


Check Out 


Check In... 


Print... 
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Opens a File dialog, which prompts for the name of the file 
to load. 7 


Saves the modified file (the option is only enabled when 
the file is modified). During the save the file is parsed and 
SNiFF+'s symbol table is updated. All tools are updated 
automatically to reflect the changes made to the file. A 
backup file can be created on every save (see 
“*,Document.MakeBackup(Bool):” in Appendix B, ETRC 
File Entries”). 


Opens a File dialog, which prompts for a new name of the 
file to save. 


Reverts to the last saved version of this file (the option is 
only enabled if the file has been modified). 


Checks out and locks the latest version of this file. The 
protection of the file is set to writable. See also “Project 
Editor with locking information shown” on page 192. 


Checks in the currently loaded file. A Log message dialog is 
opened prompting for the log message for the newly saved 
version. The file is checked in as the newest version of the 
currently checked out branch. The file is saved before it is 
checked in. After the file is checked in, the protections of 
the working file are set to read only. (See also “Project 
Editor with locking information shown” on page 192.) 


Opens a Print dialog for printing the file (see “Print 
Dialog” on page 175). | 
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The Edit menu serves to issue standard commands for selecting, cutting, 


copying, and pasting text. Furthermore, it provides the (Un) Nest and 
(Un)Comment commands, which serve to shift the current selection tabwise or 
to put comment marks in front of the current selection. 


Undo command —Undoes the last change (command) to the text. The number 
of remembered undoable commands can be specified in 
the preferences file (see Appendix B, ETRC File Entries”). 


Redo command Redoes the last undone change (command). 


Cut Cuts out the'current selection into the paste buffer (entry is 
only enabled if there is an active selection). 


Copy Copies the current selection into the paste buffer (entry is 
only enabled if there is an active selection). 


ee NOTE The Undo, Redo, Cut, Copy, and Paste commands are also accessible 
from the Edit pop-up menu, which appears in the text view when the right mouse 
button is pressed. 


Paste Pastes the paste buffer into the text at the current cursor 
location. If the cursor is a selection, the selection is 
replaced by the pasting. (The entry is only enabled if the 


paste buffer is not empty). 

Select All Selects the complete file contents. 

Nest Shifts the currently selected lines(s) one tab width to the 
right. 

Unnest Shifts the currently selected lines(s) one tab width to the 
left. 

Comment Inserts '//' comment at the beginning of the currently 


selected line(s). 


Uncomment Removes '//' comment at the beginning of the currently 
selected line(s). 
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Positioning menu 


The Positioning menu provides commands for positioning in a text file, as well as 
the “Find/Change...” command. 


Edit Superclass 
class 


Edit Overridden 
Method method 


Edit Declaration/ 
Implementation 
of method 


Edit Header/ 
Implementation 
File 


Previous Position 
Find/Change... 


Go To Line... 


Find Again 


Next Match 


+ sone If the cursor points at a symbol for which both declaration and 
: implementation exist, <Alt>E switches between them. 

If not, the first entry is disabled and <Alt>E just switches between 
the declaration and implementation file. 


Jumps to the declaration of the superclass of the currently 
loaded class (this entry is only enabled if the cursor is 
positioned in the scope of a class that has a superclass). 


Loads into Editor the overridden method of the closest 
superclass that defines method. 


Toggles between the declaration and the corresponding 
implementation. 


Toggles between the implementation file and the header 
file, and positions the cursor at the beginning of the file. 


Jumps to the previous cursor position in this file. 

Opens a Find/Change dialog for finding or changing text. 
Regular expressions may be used (see “Find Dialog” on 
page 171). 

Opens the Go To dialog, which prompts for the line 
number. 


Jumps to the next match of the search string in the Find/ 
Change dialog. This command also works if the Find/ 
Change dialog is not open. 


Loads the next match of the most recently used Retriever. 
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The Utilities menu serves to trigger various kinds of utilities. 


Update Symbol Triggers an update of the symbol table after files of loaded 

Table projects were changed with tools other than SNiFF+. All 
files belonging to the project are checked and reloaded 
(reparsed) if they where modified and hence the symbol 
table is updated (see “Make menu” on page 189). 


Hide/Show | Hides (or shows) the list of symbols used for fast 
Symbols positioning in the Editor. 


“£ NOTE Use the Build menu to execute Makeit in the Taligent Application 
Environment. 


The make menu serves to issue three make commands. The command actually 
issued by these can be specified in the Preferences dialog and in the Project 
Attributes dialog (see “Project Editor” on page 187). 


Make File Obtains a Shell and starts “make oljectfile” in the project's 
objectfile source directory. 


Make Target target Obtains a Shell and starts “make targe?” in the project's 
source directory. 


Recursively Make Obtains a Shell and starts the “make” command for all 
target subprojects bottom-up, depending on the attribute settings. 
Finally, “make target’ is called for the current root project. 


Update Makefiles Updates the dependency information for the makefiles of 
| all editable projects. This command has to be issued only 
when a new include statement is inserted in one of the 
source files of the project. This command need not be 
issued when attributes or the project structure are changed, 
in which case SNiFF+ updates the makefile information 
automatically. 
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Exec menu 


PRELIMINARY 


This menu does not currently apply to the Taligent environment. The Exec 
menu is a front end to the SNiFF+ Debugger commands and its entries are only 
enabled when the Debugger is started. 


Add Symbols of 
source file 


Debug Target 
target 


End Debugsession 


Quit Debugger 


Adds symbolic information for source file. This command 
searches for a cached object file in the generate directory 
of the project and recompiles the object with symbolic 
information before loading it. 


Starts the debugger and loads the target executable. The 
entry is only enabled if the target name is set (see “Project 
Attributes Dialog” on page 19Q) and the target is 
executable. 


Ends the current debugging session and quits the debugger 
backend (including the debugged application), but does 
not quit the SNiFF+ Debugger. The Debugger is iconified. 


Quits the SNiFF+ Debugger and the debugger backend 
(including the debugged application). 


The Inspect menu is a front end to the SNiFF+ Debugger commands and its 
entries are only enabled when the Debugger is started. 
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TAE menu The TAE menu gives you commands for starting, shutting down, and 


Makeit Complete 
Makeit (non- 


recursive) 
Makeit Testing 


Complete 
Makeit Includes 
Makeit Objects 
Makeit Libraries 


Makeit Binaries 


Create FAST 
Makefile 


LEP TELE 


The Build menu lets you build in the Taligent Application Environment. 


Executes all standard phrases of a build for the current 
project directory and all its subdirectories. 


Executes all standard phrases of a build for the current 
project directory 


Make the tests for the current project directory and all its 
subdirectories. 


Ms the Includes phase for the current project directory and 
all its subdirectories. 


Makes the Objects phase for the current project directory 
and all its subdirectories. 


Makes the Libraries phase for the current project directory 
ad all its subdirectories. 


Makes the Binaries phase for the current project directory 
and all its subdirectories. 


Forces a rebuild of the .Make file for the current project 
directory and its subdirectories, using the - fast option. 


See “Makeit” in Chapter 5 for more information. 
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maintaining the Taligent Application Environment. 


Start Taligent 
Application 
Environment 
Shutdown 
Taligent 
Application 
Environment 
Start Taligent 
Workspace 


MakeSOL 


Starts the Taligent Application Environment. This takes 
awhile, so please be patient. 


Shuts down the Taligent Application Environment. You 
should be sure to execute this option before you try to use a 
reinstalled shared library. | 


Starts the Workspace if it has been installed in your 
TaligentRoot. 


Runs the MakeSOL command. You should do this if you 
have added new shared libraries to the system. Be sure to 
shut down the system first! 


See the Taligent Installation and Release Notes for more information on these 


features. 
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Custom menus 


Placing entries in the 
Custom menu 


Adding multiple menus 
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Custom menus allow the execution of customized commands in the Editor. You 
can have as many custom menus as you want. There are two ways to define a new 
menu: 

« Modify the EditorCustomMenu config files located in $SNIFF_DIR/config. 

# Add or modify .EditorCustomMenu config files in your home directory. 


NOTE If you specify the .EditorCustomMenu in your home directory, these 
files supersede the corresponding config file in $SNIFF_DIR (and therefore you 
lose access to any customization set by your site manager). A better strategy is to 
copy the required config file from $SNIFF_DIR/config to your home, rename it, 
and then modify it with new entries. 


Entries with no specified menus are placed in the Custom menu, as in: 


shell “echo %s" "echo %s" 
shell “echo %F" “echo %F" 
shell “echo 41" “echo 41" 
filter "date" “date" 


You can add multiple menus by adding menu titles to the menu config file. To 
add a title, precede it with the “>” characters. 


“NOTE This isa greater than symbol and a space. 


This example specifies one menu: Misc. 


Shell “echo 4S" “echo 4s" 
shell "echo 4d" “echo 4d" 
shell “echo 4f" “echo 4f" 
filter "date" "date" 

> Misc 

shell "Command 1" “echo 1" 
shell "Command 2" “echo 2" 


The first menu is called Custom, the second is called Misc. 


In this next example, the first menu is called Echo, the second is called Misc. 


> Echo 

shell “echo 4s" "echo 4s" 

shell “echo 4d" “echo 4d" 

shell “echo 4f" “echo 4f" 

shell “echo 4D" "echo %D" 

shell "echo %F" “echo %F™ 

shell "echo 41" “echo 41" 

filter "date" "date" 

> Misc 

shell "Command 1" “echo 1" 
shell "Command 2" “echo 2" 
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This menu does not currently apply to the Taligent environment. After the 
command “Debug Target” is issued from the Exec menu, the Debugger is started 
and the Editor is in debugging mode. In Debugging mode the file is read only 
and a row of new buttons is added to the Editor window. 


Run Runs the debugged application from scratch. 
Cont Continues the interrupted execution. 
Step | Single steps into the next function/method. 
Next Single steps over the next function/method. 
Break In Sets a break point at the current selection, whereby selection © 
must be a valid function/method name. 
Break At Sets a breakpoint at the current cursor position (linewise). 
Clear Clears the breakpoint at the current line. The cursor must 


be positioned to a line with a breakpoint. 


Print * Prints the value pointed to by the current selection. Selection 
must evaluate to valid pointer. 


Print | Prints the value of the current selection. Selection must 
evaluate to a valid variable. 


this Prints the value of the current object. 

Stack Opens a stack trace window and displays the current call 
stack. | 

Up Goes one stack frame up in the call hierarchy. A reusable 


Editor is automatically positioned at the source location of 
the new stack frame. 


Down Goes one stack frame down in the call hierarchy. A reusable 
Editor is automatically positioned at the source location of 
the new stack frame. 
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and goodies 


Selecting text 


Marking of matching 
language items 
(brackets and quotes) 


Fast copying 


Copying and moving 
with direct manipulation 
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The are three ways to select text. 
# Characterwise by clicking and dragging with the mouse. 
« Wordwise by double-clicking and dragging with the mouse. 
« Linewise by triple-clicking and dragging with the mouse. 


Double-clicking close to any of the following language elements: 
single quotes—' — 
double quotes— “ — 
parentheses-— ( — 
brackets— [ — 
braces— { — 


causes the Editor to mark the code between this item and the matching one. 


To avoid the overhead of copy/paste, a fast copy command can be used. Pressing 
the <Shift> and <Ctrl> keys at the same time and selecting a text to be inserted 
will copy this text to the current cursor position. 


Another possibility is copying with direct manipulation. 


Clicking with the mouse on an active selection and dragging the text to a new 
position will move the selected text. Pressing the <Ctrl> key while dragging will 
copy the text instead of moving it. 
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DOCUMENTATION BROWSER 


Icon menu ————~ 
reflects editing 
state 

- read-only 

- not modified 

- modified 
currently: 
modified 


Tool is 
reusable 


SNiFF+ lets you view and edit class and member descriptions in a special 
Documentation Browser. 


Like the Editor, the Documentation Browser consists of a WYSIWYG text Editor 
and a list of classes, methods, functions, and data defined in this file. This list 
speeds up the positioning by displaying the description when a symbol is 
selected. 


canst 


Same as class. XXXHx M INT 

urpose: 
SKE M PUR 

Calling Context: 
IE M_CAL 

arameters : 

Takes no parameters. - EKXXEX M PAR 

Return Value: 


EXEKK M RET 
xceptions : 


Throws no exceptions, passes all exceptions through. 


Throws EXXXX EXCEPTION 1f X2EXX_M EXC 


Same as class. XXXXX_M CON 
Other Considerations: 
KKEXKE_M_ OTH 


TAudioType : : SetFormat 
void SetFormat (const TToken &) 
Interface Category: 
Same as class. XXXXX_M INT 
urpose: 
MEEKK M PUR 
Context : 


MEKKE M EXC 


FaudioExceptions 
GetaLaw (md) 
GetAéLaweéKHe (md) 
GetFormat (md) 
GetLinear (md) 


GetLinearl6Bbit44kHz f: 
GetLinearghitegKHs (mi 


GetMuLaw (nd) 
GetMuLawSKHe (md) 


Get0ffsetBinary (md) 
GetOffsetBinarysbi ted: 


GetSampleRate (md) 
BetSampleWidth (md) 
Hash (md) 

IsEqual (md) 
operator<<= (md) 
operator= {md} 
operator>>= (md) 
PrintDebugInfo (md) 
SetFormat (md) 
SetSampleRate (md) 
SetSampleWidth (md) 
TaudioType (cl) — 
TaudioType (md) 


typedef char Samp LeSE 


Class pop-up 
menu either 
shows all 
classes or 
only one 
class 
(current 
setting) 


Symbol list 
defined by class 
pop-up menu 
(clicking ona 
symbol 
positions the 
cursor) 


| Displays list 


alphabetically 
or in order of 
appearance in 
the file 


When a file is edited, the icon of the Icon menu changes to a warning sign until 
the file is saved. 


File is not writable _ File is writable File is modified 


The entered text is automatically reformatted. The time interval between 
reformatting can be set in the ETRC file (see “ETRC file entries” on page 261). 
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The Symbol List is constrained by the Class pop-up. 
“md” indicates method declarations 
“cl” indicates class definitions 
« “f indicates functions 


The Documentation Browser is positioned at the symbol by clicking on an entry 
in the Symbol List. 
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The class pop-up scopes the Symbol List to either show only symbols of one class 
or to show all symbols of this file. This feature eases navigation when there is 
more than one class defined in a file. 


The Documentation Browser's File menu contains standard commands for saving 
files. 


Load Opens a.d file directly, instead of using the Info menu. 
Displays a file dialog from which you can open the Docs 
directory and select the .d file you want to use. 


Save Saves the modified file (the option is only enabled when 
the file is modified). During the save the file is parsed and 
SNiFF+'s symbol table is updated. All tools are updated 
automatically to reflect the changes made to the file. A 
backup file can be created on every save (see Appendix C, 
“ETRC file entries”). 


Revert Reverts to the last saved version of this file (the option is 
only enabled if the file has been modified). 

Check Out (Do not use in this release) 

Check In... (Do not use in this release) 

Print... Opens a Print dialog for printing the file (see “Print 


Dialog” on page 175). 
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Edit n menu The Edit menu serves to issue standard commands for cutting, copying, and 
pasting text. 


-Undocommand —_ Undoes the last change (command) to the text. The number 
of remembered undoable commands can be specified in 
the preferences file (see Appendix B, “ETRC File Entries”). 


Redo command Redoes the last undone change (command). 


Cut Cuts out the current selection into the paste buffer (entry is 
only enabled if there is an active selection). 


Copy Copies the current selection into the paste buffer (entry is 
only enabled if there is an active selection). 


Paste Pastes the paste buffer into the text at the current cursor 
location. If the cursor is a selection, the selection 1s 
replaced by the pasting. (The entry is only enabled if the 
paste buffer is not empty). 


=@ NOTE The Undo, Redo, Cut, Copy, and Paste commands are also accessible 
from the Edit pop-up menu, which appears in the text view when the right mouse 
button is pressed. 
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Styles menu The Styles menu formats text. 


Default text Changes the selected text to the default text font. 
Emphasized text _Italicizes the selected text. 


See the Class and Member Style Guide for details on formatting class and member 
function descriptions. | 
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Info menu See “Info menu” on page 179. 
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Class menu See “Class menu” on page 180. 
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TAE menu See “TAE menu” on page 220. 
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Custom menus See “Custom menus” on page 221. 
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SHELL 
SHELL 
The Shell is a front end to the regular UNIX command line interface. It can be 
used for system-level manipulations, and it is used by SNiFF+ to issue make 
commands. Furthermore, it serves to select an error message and to trigger the 
marking of the corresponding source code with the “Find Error” command of 
the Shell menu. 
Icon 
oe gcd “home /chris/f1ilebrowserII 
| sunsh3% make | Make called by SNiFF+ 
etC0 -q -l/Users/joe/Sniffe/et3/sro -c BrowserView. C 
BrowserView.C: In method ‘BrowserView: :BrowserView fclass 
VET EvtHandler*, int)’: Wee 
: BrowserView.0:43: parse error before string constant Compilation error 
d*+* Error code 1 click to it and select “Find 
jd make : Fatal error: Command failed for target ‘BrowserView.o’ Error’ from the Shell menu 
j sunsb3 ” 
Tool is | 
reusable 
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Edit menu The Edit menu of the Shell contains the usual Cut/ Copy/Paste/Find commands 
plus a Clear command. 


Clear Clears the complete Shell buffer. 
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The Shell menu serves to issue three commands. 


Find Error 


Reconnect 


Auto Reveal On/ 
Off 


Filters the line containing the cursor. If it understands the 
error message format, it obtains an Editor and displays the 
corresponding source code. Section “Error formats file” on 
page 241 explains how to extend the list of understood 
error formats. 


Reconnects to a new shell. 


Turns the auto-reveal feature on and off. If auto-reveal is on 
and input is typed or sent from a process, the Shell 
automatically scrolls to reveal the new text (this is the 
default). 


‘_@ NOTE This menu does not apply to the Taligent Application Environment. 


The target menu serves to make and run the target executable of the root 


project. 


Make Target target Obtains a Shell and starts “make target” in the project's 


Recursively make 
target 


Run target 


Debug Target 
target 


source directory. 


Obtains a Shell and starts the “make” command for all 
subprojects bottom-up, depending on the attribute settings. 
Finally, “make target’ is called for the current root project. 


Obtains a Shell and executes target. 


Starts the debugger and loads the target executable. The 
entry is only enabled if the target name is set (see “Project 
Attributes Dialog” on page 199) and the target is 


executable. 
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CUSTOMIZING YOUR ENVIRONMENT 


override user preferences, which in turn override site preferences. 


General tool Templates for Configuration Extensions to Project Custom , Location 


preferences newly created file forthe infor- the Retriever's —_ attributes menus 
source files mationextrac- Filter menu 
tor 


saaannnntnentnnnnnane SNiFF+ 
: installation 
| Site T: directory 
: , | : | | | merges/ 
. a = a a eee os i ee . as Pets or? 2 overrides 
ETRC | Template | | User's 
OBE 
DOD Aen ce ee ek ee ee ee ee oe eee lee oe ante oe Bee “pnts merges/ 
| overrides 


| ; | | | 

| | Parser config ( Project | j | z 4 User's or 
! ai ication 
. | | ocation 


Each user of SNiFF+ has a private set of preferences. General preference settings 
are stored in a file called ETRC, located in the user's home directory. The most 
important and frequently changed settings of that file can be manipulated with 
the Preferences dialog. The other settings must be edited in the ETRC file 
directly (see “ETRC file entries” on page 261). 


As shown in the illustration above, other preferences and configurations are 
stored in separate files. 
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Files, Directories & Paths 
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SNiFF+'s Preferences dialog serves to browse and edit a number of settings that 
apply to all your projects. Some of these settings can be overridden in the Project 
Attributes dialog (see “Project Editor” on page 187). Generally, changes to the 
preferences take immediate effect. Exceptions to this rule are noted in the 
descriptions below. | 


SNiFF+ expands file and directory names using the C shell. Shortcuts such as the 
“~" or $variables may therefore be used and are expanded correctly. 


Template Indicates the directory where the personal template files 
Directory are stored. These template files are used when a new source 
| file is created (see “Project menu” on page 190 and “Files 
created and used by SNiFF+” on page 230). 


Manual Path Contains a list of directory names separated by colons. 
These directories are searched for class and member 
descriptions when the “Show Documentation of” command 
of the Info menu is issued (see “Documentation Browser” 


on page 224). 
Retriever Filter Indicates the file where extensions to the Retriever's Filter 
File menu are stored (see“Files created and used by SNiFF+” on 


page 239 and “Retriever” on page 210). 
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Sizes 


Flags 


PRELIMINARY 


Include Suffixes 


Source Suffixes 


History Size 


Default Tab Size 


Retriever Cache 


Motif Look 


Store Window 
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Describes the valid suffixes of header files. Suffixes are 
separated with colons. The default is “h:hxx”. 


Describes the valid suffixes of implementation files. Suffixes 
are separated with colons. The default is “c:cc:C:cxx”. 


“© NOTE The point separating file name from suffix must be omitted. 


Specifies how many previous states are kept in the history 
buffer of every tool. 


Defines the default size for tabulators. This attribute can be 
overridden for each project separately in the Project 
Attributes dialog. 


Specifies whether SNiFF+ caches files once they were 
searched by the Retriever tool. This option can speed up 
cross referencing considerably but it increases SNiFF+'s 
RAM requirement by the size of your files (which is 
frequently negligible). 

Specifies the look SNiFF+ selects at start-up. You can choose 
between Motif look and native ET++ look. Native ET++ look 
is superior on a black and white screen. Otherwise the 
selection of the look is a question of personal taste. A 
change takes effect on next SNiFF+ start-up. 


Defines whether the state of your current working 


Positions environment is stored on closing a project and restored 
when it is loaded the next time. Default is to store window 
positions. 

Auto Popup Specifies whether the Error log window (see “Error log 

Error Log window’ on page 177) is automatically opened when a 
message is written to it. Default is not to open the window. 

Use Emacs _ Determines the main Editor used by SNiFF+. You can 
choose between the SNiFF+ integrated Editor and Emacs . 

Read-Only Changes documentation file from read-only to read-write. 

Documentation The icon on the Documentation Browser changes to 
indicate the file is writable. Toggle to change back. 
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Other Options 


Make Command Specifies the command to be submitted to the shell when a 
make command is issued (see “Project menu” on page 
186). The default is “make”. If you compile on a compile 
server, you can change the command, for example, to “on 
server make”, or you can provide your own shell script to do 
fancier things. | 


Sniff Server Host Indicates the host in the network where the information 
extractor process (sniffserver) runs. The default is no host 
(empty string), which means use a server process on the 
local machine. 
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SNiFF+ supports teamwork in several ways: 


# Projects can be frozen. This prevents anybody from making changes to the 
project. 

« Version control systems can be integrated (see “Version control” on page 
254). | 

# Shared files can be overlaid. 


Files of a common subproject which are shared by several developers can be 
copied to the directory of a root project. If the overlay files attribute is enabled 
for the subproject and the superproject (see “Project Attributes Dialog” on page 
199), the shared files are hidden by their copies. The developer works 
transparently with the copies, and on linking the target, the object files of the 
copies are linked. Hidden files are marked in the Project Editor with the string 
“hidden”, and during the loading of a project SNiFF+ notifies the developer in 
the Error log window about the files that are hidden. 


Later on, the overlaid version can be merged into the shared version. This can be 
achieved by using the version control tools (see “Version control” on page 254) 
or by running the two versions through the UNIX diff facility and by manually 
merging the changes. 


@ NOTE Files are only overlaid if the Overlay Files attribute is set in the Project 
Attributes dialog of the project to be overlaid and the overlaying project. 
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When running, SNiFF+ consists of several processes: two of them are the SNiFF+ 
programming environment (sniff) and SNiFF+'s information extractor 
(sniffserver). The information extractor is a fuzzy C++ parser which analyzes 
C++, ANSI C, or Kernighan & Ritchie C source files and sends the programming 
environment a stream of information about the symbols defined and declared in 
the source code. 


The sniffserver process can run on the local workstation or on any workstation 
on the network. The default behavior is to start the sniffserver process locally. If 
the process is to be started on another workstation, this can be indicated in the 
Preferences dialog (see “Preferences” on page 231). 


NOTE If SNiFF+ does not find a running sniffserver process, it tries to start 
one. If the server is to be started on the local workstation, the sniffserver 
executable is to be found in one of the command directories. If the server has to 
be started on a remote workstation, a shell script called startsniffserver has to 
be found in one of the command directories. 


Running the Running the sniffserver process on a workstation other a the programming 
sniffserver on a environment can make sense for several reasons. 
different host 


If main storage is scarce on the local machine, it can make sense to put the load 
on a workstation with more RAM. 


There are frequently fast server workstations on a network that can considerably 
shorten parsing time. This effect is not relevant during programming, when only 
single files are parsed at a time. But it can shorten start-up time when a large 
project has to be loaded. 


Parsing on the workstation where the source code is physically stored reduces 
network traffic. Once again, this effect is not relevant during programming, 
when only single files are parsed at a time. It becomes relevant at start-up time, 
when a large project is loaded, or when many developers are working on projects 
located on the same server. 
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How to run the sniffserver 


on a remote host 


ae CE ne nr as 


Dealing with 
preprocessor macros 


Several things are necessary to run the sniffserver process on a remote host: 


# The “Sniff Server Host” entry of the Preferences dialog (see “Preferences 
dialog” on page 232) must contain the name of the host where the 
sniffserver process is running. 


« The file /etc/services must contain an entry similar to this: 


sniffserver <port_num>/tcp 


where <port_num> is an arbitrary unique tcp port number greater than 1024. 
If your computers run with Yellow Pages (YP) or NIS, then the entry should 
be made in the tables of the YP/NIS server. Please contact your system 
administrator to do that. 


# If the sniffserver is not running on the remote machine, SNiFF+ executes 
startsniffserver, which has to be found in the command directories. 
startsniffserver is located in the <sniff_directory>/bin directory and isa 
shell script using the on command to start the sniffserver on the remote 
machine. Several restrictions apply for using the on command (see the UNIX 
manual pages). If the on command does not work, then you can start the 
sniffserver manually on the remote machine with the following command: 


$SNIFF_DIR/bin/sniffserver <remote_hostname> 


where <remote_hostname> is the host name of the machine running the 
sniffserver. 
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SNiFF+'s information extractor does not expand preprocessor macros when it 
parses source files. This approach has the advantage of speed, but occasionally 
some preprocessor macros confuse the parser. 


SNiFF+ provides a mechanism to solve these kinds of problems by configuring 
the parser. For every project, you can write a file containing directives for the 
parser (see “Parser configuration file” on page 239). 


The location of this file is defined with “Parser Config File” attribute in the 
Project Attributes dialog (see “Project Attributes Dialog” on page 199). After 
changing the configuration file, you should force a reparse of the project 
(“Project menu” on page 190). 


The following examples illustrate how to configure the parser in case of 
problematic preprocessor macros. 


TALIGENT TOOLS FOR AIX TALIGENT CONFIDENTIAL: REGISTERED INFORMATION 


) 
7: 


PRELIMINARY 


Spapahecteb ati ceis ey arco ene SE dc de ESO POOPED RCT eD DRED DRE pb aes tgp aries mes pp, 


CHAPTER 14 CUSTOMIZING YOUR ENVIRONMENT 
_ INFORMATION EXTRACTOR (SNIFFSERVER) 


PLP EOC CLEP CEEOL OOTP L ELE EEE EE ELE L EEE ELLE LEE ETE EE NE TATE EEE LETTE EEE LL EEE CEE EEE EEE EEE LEE ELEC EEE EOE T EEE TE CE 


Configuring the parser 


Preprocessor macros to 
be ignored by the parser 


#ifdef directives to be 
resolved by the parser 


The VIRTUAL macro is used in the NIH class library in class definitions like this: 
class A : public VIRTUAL B 
ean 
The VIRTUAL string can be ignored without losing information. 
Strings to be ignored can be defined with ignore string string tuples in the 
parser configuration file. In the case of NIH this is: 
ignore string VIRTUAL 
Don't forget to reparse the project after the configuration file has been changed. 


Some class libraries use the preprocessor directive #ifdef to modify the code ina 
way that confuses the parser. 


Examples are: 


« Different class definitions for the same class selected with an #ifdef: 


ifdef UNIX 
Class someClass : unixBaseClass 
#else 
Class someClass : otherBaseClass 
itendif 
Ie ee 1 
Since SNiFF+ normally parses the whole code without resolving #i fdef, it 
reads two class definition headers and just one actual definition. 
To solve this problem add the following line to the parser configuration file: 


define UNIX 
This tells the parser to ignore the line between the #else and the #endif 
directives. Alternatively, you could add this line to the configuration file: 
undefine UNIX 
The parser will ignore the line between #ifdef and #else. 


# Unbalanced braces: 


#Hifdef HUGE_INT | 

for (int i=0; i<MAXVAL; i++) { 
dtelse 

for (long i=0; i<MAXVAL; i++) { 
dtendif 

. I 
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#if directives to be 
resolved by the parser 


Since SNiFF+ normally parses the whole code without resolving the #i fdef, it 
reads two opening and only one closing brace. To solve this problem add the 
following line to the parser configuration file: 


define HUGE_INT 


Another possibility to solve this particular problem is to remove the opening 
brace from the two for lines and put it after the #endif directive. 


Sometimes it is necessary to resolve #if directives. For example: 


#if defined (UNIX) || defined (VMS) 
class someClass : unixBaseClass 
#Felse 
class someClass : otherBaseClass 
dtendif 
te ge pe 


The expression after the #if directive will be evaluated if it contains only the | |, 
&&, | (logical negation), defined operator and parentheses for grouping. If the 
expression contains other operators or a defined operator with an identifier that 
does not appear in the parser configuration file, then the #if is not resolved (i.e. 
both branches will be parsed). Assuming that your configuration file contains 


define AAA 
undefine BBB 


Then from the following source code, only a, d, e and f will appear in the symbol 
table. 


#if defined(AAA) 
int a; 
#Felse 
int b; 
dtendif 
#if defined(AAA) && defined(BBB) 
int c; 
dFelse 
int d; 
endif 
if defined(CCC) 
int e; 
dtelse 
int f; 
dtendif 


TALIGENT TOOLS FOR AIX TALIGENT CONFIDENTIAL: REGISTERED INFORMATION 


PRELIMINARY 


CHAPTER 14 CUSTOMIZING YOUR ENVIRONMENT 
FILES CREATED AND USED BY SNIFF+ 


PELL ELLE POOL MEER EEO EO POE OEE O LE EOE ELODIE LL EDN ELIE OEE OOO COLL LEO O CEO AO LOOM ID LNA OO ODL L OEE GED GLICO OE OEIC OID PME EN GOO EM ELLIO ELC OOEP IOI ON 


Project file A project file describes a SNiFF+ project and is stored at a location indicated by 
the developer. A project file stores only structural information and attributes of a 
project. No source code or symbolic information is stored there. Project files are 
usually just a few KB in size (see also “SNiFF+ projects” on page 244). 
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ETRC file | The information manipulated in the Preferences dialog is stored in the ETRC 
file in the home directory of every SNiFF+ user (see “Preferences” on page 231 
and “ETRC file entries” on page 261). 


Parser configuration The parser configuration file contains special configuration instructions for the 


file SNiFF+ information extractor (sniffserver). It can be defined for projects using 


preprocessor macros that semantically change the source code. For further 
explanations, see “Dealing with preprocessor macros” on page 236. 
The file can contain lines with 


“ Ignore string string 
The parser just ignores string in the source code. 
« Define symbolor undefine symbol 


The parser resolves #ifdef containing symbol. #ifdefs not containing symbol 
are parsed completely. 


The location of the file can be specified with the Project Attributes dialog (see 
“Project Attributes Dialog” on page 199). 


## Example ignore strings file 


# 

ignore string VIRTUAL ## for NIHCL 

ignore string _C_ARG1 # for the License project 
define UNIX # resolve ifdefs for UNIX 
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Custom menu file 


Syntax 
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The file describes filters that should be added to the Filter menu of the Retriever 
and consists of a sequence of lines of '"' delimited string pairs. The first string is 
added to the menu and the second string is the regular filter expression that is 
applied on selecting the corresponding menu entry. In formulating a filter 
criterion, the string “%s” can be inserted several times. It will be expanded with 
the actual match for every retrieved source line. 


The Preferences dialog can be used to tell SNiFF+ where to find the filter 
extension file (see “Preferences” on page 231, “Retriever” on page 210, and 
“ETRC file entries” on page 261). 


## Example Retriever filters file 

li 

"call METHOD" "%s[(].*3;" 

"declare class::METHOD" "[A-z0-9_ \t]+::%s[%; ]+$" 
"CLASS: :method/var" "%s::.¥*;" 

"class::METHOD/VAR" "[A-z0-9_ \t]::%s.*;" 
"->METHOD" "->%s[E(]" | 

"OBJECT->method" "%s->[A-z0-9_ \t]+[£(]" 

"->VAR" "->%s[*(A-z0-9_]" - 

"OBJECT->var" "%s->[A-z0-9_ \t]+[*(A-z0-9_]" 
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Template files are loaded into newly created project source files (see “Project 
Editor” on page 187). Templates must be called template. extension, whereby 
extension is one of the allowed extensions for header and implementation files. 
The location of template files and the list of allowed extensions can be specified 
with the Preferences dialog (see “Preferences” on page 231). 


SNiFF+ allows the definition of commands which are accessible from the Editor 
via the Custom menu. The file specifying the menu is called .EditorCustomMenu 
and is located in the user's home directory. 

Site-specific custom menus may be defined in the config directory of the SNiFF+ 
installation. The name of the file must be: EditorCustomMenu. The files are 
loaded during start-up. 


CustomMenu={CustomMenuEntry}. 


CustomMenuEntry=Descriptor MenuString Command 
|[Separator. 


Descriptor="shell" | "debugger" | "filter". 
MenuString=sinng. 
Command=siring. 


Separator="-" 
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A “shell” command is executed in aSNiFF+ Shell. 
A “debugger” command is sent to the Debugger. 


A “falter” command is any kind of process. Its input is the current selection in the 
Editor and its output replaces the current selection. 


A separator Causes the insertion of a line in the menu. It is used for esthetic 
reasons only. 


Commands are expanded as follows: 


%dProject file name 

%f Source file name 

%sCurrent selection 

*DSource directory 

%FBasename of source file 

%1Locking path without the RCS/SCCS extension 
(used by the version control system to store the 
version files) 


Strings may be delimited with double quotes (“”) if they contain blanks. 


## Example EditorCustomMenu file 

i 

shell "RCS diff" "rcsdiff -kk %1/RCS/%F,v %f" 
shell "SCCS diff" "cd “4D; sccs -d%1l diffs “F" 


filter Date date 
shell "Load File Into vi" “cmdtool vi “4f" 


debugger "Info Files" “info files" 
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SNiFF+ integrates various compilers and other tools (like Purify). The Shell 
(“Shell menu” on page 228) and the Debugger (see “Icon menu” on page 177) 
are able to interpret the output messages of such tools based on a configurable 
error- formats file. The file $SNIFF_DIR/config/ErrorFormats contains a list of 
regular expressions for the most common error formats. If the error messages of 
your compiler are not covered by an entry in that file, you can add the 
corresponding regular expression. Regular expressions are explained in “GNU 
Regular Expressions” on page 257. 
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Supplied ErrorFormats file 


Files s canaraiad iy: 
SNiFF+ and stored in 
the generate directory 


Make support files 
(dependencies.incl and 
ofiles.incl) 


Symbol table files 


Window status files 


d¢ SNiFF+ - regular expressions for compiler error messages 
# "file.c", line 123 


NCES, aeA) eh ]+lineL J+\([0-9]J+\) 
dt file.c, line 123 

\([4 1+\),£ J+linel ]+\([0-9]+\) 

d Purify: [line 123, file.c, 

Tinef J+\(({0-9]+\),0 J+\ (04, ]+\) 


# file.c:123 

\CC*%: +N): 0D) J*ACLO-97+\) 

# file.c(123) 

\(L* J+\.0% J+\) (\CL0-994N)) 
The parts of the regular expression that match the filename and the line number 
must be enclosed in a \(_ \) construct. Each regular expression must have exactly 
two such constructs. 


For every project, SNiFF+ creates a directory that serves as a container for all 
project-dependent files generated by SNiFF+. Its location and how it can be 
changed is described in “Project Attributes Dialog” on page 199. 


For every project a dependencies. incl file is generated that describes the include 
dependencies between the files of the project and its subprojects. An 
ofiles.incl file is generated that defines which object files have to be linked in 
building the current target. For a further description of how to use these files, see 
“Makefile Support” on page 249. 


SNiFF+ dumps symbol table files to the generate directory specified in the 
Preferences dialog (see “Preferences” on page 231). For a detailed description of 
symbol table persistency, see “Tuning and persistency of symbolic information” 


on page 243. 


Window status files are created by SNiFF+ for every user and are stored in the 
generate directory. These files are named <project_name>.<user>.state and 


store the position and contents of windows, the location of split handles and the 


cursor positions when the project is closed. The next time the project is Spence 
the file is read in and the windows are restored. 


TALIGENT TOOLS FOR AIX TALIGENT CONFIDENTIAL: REGISTERED INFORMATION 


PRELIMINARY 


creel teleeeeiietienreieceretaieriebecccrerrriccictrns, 


persistency (default) 


PCE 


CHAPTER 14 CUSTOMIZING YOUR ENVIRONMENT 
TUNING AND PERSISTENCY OF SYMBOLIC INFORMATION 


SNiFF+'s tools always work with the newest symbol information since they use the 
central symbol table (database) that is held in memory. The symbol table always 
is up to date and refers to the newest source code. This is possible because 
SNiFF+ directly uses the source code to extract the symbolic information. The 
information extractor is a very fast and lean parser. Once a project is loaded and 
parsed, all queries are executed in memory only — that is the reason why SNiFF+ 
scales linearly, and even huge software systems can be handled efficiently. 


For smaller software systems up to 25 KLOG, the project loading time is no 
problem and information can be extracted on the fly. 


For bigger projects (more than 25 KLOC), information extraction from the 
source code on every project load would be too time consuming, even with the 
very fast information extractor. 


Therefore SNiFF+ allows the symbol table to be efficiently persistent between 
SNiFF+ sessions. Symbol table persistency is fully transparent to the user. 


Depending on the kind and size of project, the user can choose between two 
different persistency models. 


After the first information extraction of a newly created project, SNiFF+ stores 
binary symbolic files for each source file in the generate directory for the project. 
The binaries are compact and efficient images of the symbol table held in 
memory. On each project load, SNiFF+ checks whether binary symbol files exist 
and loads them directly into memory instead of extracting the information from 
the source files. Information extraction from the source code is still possible if 
the source file is more recent than the binary symbol file. This can only happen 
when the source has been changed with a foreign tool or the date of the files has 
been otherwise modified. 


s 
roject-ievei symbo 


persistency 


For library projects that are never changed, it makes sense to dump a single 
symbol table file for the whole project. This project symbol file is even more 
efficient and also much faster in loading. A project symbol file can be dumped 
(or actively removed) with the “Dump/Remove Symbol Table” command of the 
Project menu of the Project Editor (see “Make menu” on page 189). 


After the project symbol table has been dumped, SNiFF+ transparently manages 
this symbol file. If the library status of a project for which a project symbol table 
exists is changed to writable, the symbol table file is automatically removed and 

file-based symbol table persistency is used. 
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loading times SNiFF+ (the files of the project are located on the local system hard disk): 
Kind of symbol loading Relative loading time 
Loading the symbols via the information 100 % 
extractor 
(parsing all source files) 
Loading individual symbol files (file-level 70% 
symbol persistency) 
Loading one project symbol table dump 40 % 


(project-level symbol persistency) 


The gain for project-level symbol persistency can be even bigger for projects 
located on NFS file systems. 


POLE LI LILLIE EPLL PILI L ELIE ALLE MIDI LPAI OES, PPLE PLLLPL ILS OLLLIS LLLP LEED EOL LILLIE PD LEP OOOO OIL ILL L ELLE DOLE LLISILOD PLE LED AEP ELODIL ILI L DEOL LEED I LLL PEI O LO DI LLL L ELLIE LILI III LILO EL EP ELL OL ILI LE IE LL EIDE BOPP OLOLILIL ODPL PILL LLL EE PIL IOSL ODP OP LIED POEL LOLOL LEEL ELL ELL LLL OLIL EEL ELIS IL ELIDLLILL OLE IPILLL OLD IPED PLLPLLLLE LI IEP IO PPEL: 


Projects in SNiIFF+ A SNiFF+ project is a collection of source files and possibly a collection of 


subprojects belonging to the project. Projects are described and saved in project 
files. 


Saving a project into a project file stores all information into that file. Opening a 
project file opens the complete project and loads all symbolic information and 
restores the window status. 


EA Slly’| filebrowser. proj _ ~~ Root project 


Pally] et.proj —----- nee ee Subproject 
Pally] CONTAINER. proj 


——.. Subproject of subproject 


If a project (project files) is opened in SNiFF+, it always forms the root project. 
Root projects are shown as the root in the project tree view of the different tools. 
Subprojects are shown as descendants. A subproject can also be opened on its 
own. 


In the example above, filebrowser.proj is the root project, et .proj is the 
subproject, and CONTAINER. proj is the sub-subproject. 
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et.proj can also be opened on its own and is then the root project and © 
CONTAINER. proj would be its subproject. 


On every project open, the symbolic information of all subprojects is loaded. 


The Project Editor (see “Project Editor” on page 187) serves to define the 
structure, the source files and the attributes of a project. 


The rest of this chapter describes how to create projects that have a complicated 
structure or that have header and implementation files in separate directories. 


POOLE CELLO TELL ELLE ECL E EE EEE EM EEL EEE EE EL EEE LECCE ELLE EEL EEE ECCT CECE CEEOL ECL ELEE EO EE EEL EEL ELEC ECOL TCE E EOE LCE EET 


Declaration and SNiFF+ requires a project per directory. Sometimes software systems have 

implementation files declaration (.h) and implementation (.C) files separated in different directories, 

in separate directories = but you would like SNiFF+ to treat such systems as if the files were all in one 
directory. SNiFF+ should therefore manage the different directories 
transparently. 


To achieve that: 


Create a SNiFF+ project for the directory where the declaration files (.h) are 
stored. 


Create a SNiFF+ project for the directory where the implementation files 
(.C) are stored. 


Load the project containing the implementation (.C) files as subproject of 
the declaration (.h) files project. 


ZI Close both projects. 


When you reopen the declaration files project, you will also get the 
implementation files. This method of creating subprojects and loading them ina 
main project can also be used with more than two subprojects. 


Example (interViews) The declaration files of InterViews are in the subdirectory src/include/ 
InterViews, and the implementation files in the subdirectory src/1ib/ 
InterViews. 


To create an InterViews project: 


Create a SNiFF+ project for the src/include/InterViews directory. Name it 
IV. 


Create a SNiFF+ project for the src/1ib/InterViews directory. Name it 
IV.impl. 


Using the Project Editor of IV, load IV.imp] as asubproject of IV. 


EX Close IV and IV.imp] and reopen the IV project. 
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PPPOE ECE CEEOL OEE EE LOOP EEPL ELLE CLE OE EOE EE LOPE OLEL PEEL 
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subprojects 


ELLIOTT EL EEL 
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If you are working on a big software project, you probably have a hierarchy of - 
directories and subdirectories, each containing the files of subprojects. Creating 
these subprojects one by one, as SNiFF+ requires, may be a time-consuming task. 


Therefore, we supply a tool called genproj that walks a directory tree downwards 
and creates project files for every subdirectory. 


Genproj is given the name of the directory that is the root of your software system 
and it generates project files in every subdirectory. 


Genproj accepts the following parameters: 


- genproj <source_dir> [-e] [-f] [-p <proj_name>] 
[-d <destination_dir>] [-s <sniff_directory>] 
[-i <ignore_dir>] 
<source_dir> is the only mandatory parameter. It is the name of the root 
directory of your software project. Genproj will walk this directory downwards 
and generate project files for every subdirectory. | 


<proj_name> is the name you want to give to the root project. If you don't specify _ 
a project name, genproj will use the base name of the source directory. 


<destination_dir> is the name of the directory where you want to keep the 
generated project files. If you don't specify a destination directory, the project 
files will be generated in the corresponding subdirectories. 


<sniff_directory> is the name of the directory where SNiFF+ stores the 
persistent symbolic information and other project-related data. The directory 
must already exist before starting SNiFF+. By default the directory is named 
.sniffdir, and it is created in the source directory of the project. 


<ignore_dir> is the name of a directory (only the name of the directory and not 
the complete path) that should not be walked down. By default, genproj ignores 
all the directories whose name starts with a dot and the directories named SCCS 
and RCS. You can tell genproj to ignore additional directories by specifying the - 
i flag for each directory. 


When specifying directories, you can use environment variables (but you must 
put their names in single quotes to prevent the shell from expanding them). The 
environment variable names will be copied literally into your project files. This 
will make the relocation of your software system easier, because you do not have 
to regenerate project files. Just modify the value of the environment variable and 
restart SNiFF+. 
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A project file will be generated only if the subdirectory contains source files (i.e. 
files whose suffixes are determined by “File Suffixes” attributes of the Preferences 
dialog; see “Preferences” on page 231), or if the subdirectory has other 
subdirectories that have source files. If you do want to have project files for 


subdirectories with no source files and no subprojects, then invoke genproj with 
the -e flag. 


Genproj generates unique file names for projects. When it detects a name 
conflict, it uses the name of the parent project (with an underscore) as a prefix. 
The root project name is never changed. If you want genproj to prefix the names 
of all projects (except the root) with parent project names (even when there is 
no name conflict), then invoke it with the - f flag. 
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CHAPTER 15 


SUPPORT FOR OTHER 
FUNCTIONS 
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ere i seediae 


SNIFF + assumes that projects are compiled and linked with the make command = be Be 


compiling and Tne and the necessary options saith a set of anables and rules. 


SNiFF+ supports makefiles with two files (dependencies.incl and ofiles.incl) 
that make it possible to use the same makefile for different projects without 
modifying it. 

The files are created in the generate directory of the project (usually .sniffdir). 
Whether the files are generated is determined by the Project attributes (see 
“Project Attributes Dialog” on page 199). 


PPL L LLL OP LLLP DLO OOOO DL OPIL EEL ILA LLY ODEN OEP MIL ELLIE EEL ILL IDELILIP IIL EIDE LEI EILPAIIGOLEEPD ILLIEDILIL ED LILLIE LELILOSPIIPLP ILL POLLED DEM ILIL IPE LIOOL LEE OODLE LOE n 


Dependencies Since SNiFF+ knows all about a project, it also knows about dependencies 

(dependencies. incl) between the files of a project, even if the dependencies exist over project/ 
subproject boundaries. On each save of the project file, SNiFF+ updates the 
dependencies and stores them in a file called “dependencies.incl” in the 
generate directory of the project (see “Preferences” on page 231). 


This file stores the dependency information in a form understood by make and 
can therefore be included in the makefile. 

©42NOTE The “Update Makefile” command of the “Make” menu of the Editor 
essen the update of the dependency information. You should issue this 
command when you add a new include file to one of the project sources. 


PRELIMINARY TALIGENT CONFIDENTIAL: REGISTERED INFORMATION TALIGENT TOOLS FOR AIX 


250 CHAPTER 15 SUPPORT FOR OTHER FUNCTIONS 
EMACS INTEGRATION 


## Example makefile showing how to include dependency and 
## object file information generated by SNiFF+ 


i 

~-SUFFIXES: .C 

CCFLAGS = -g 

LDFLAGS = 

CC = etCC $(CCFLAGS) 
.C.o: CC -dump $(CCFLAGS) -c $< 
C20: 


cc $(CCFLAGS) -c $< 
include .sniffdir/ofiles.incl 


Object ——_————— myApp1: $(OFILES) 
file list $(CC) $(LDFLAGS) -o $@ $(OFILES) 


include .sniffdir/dependencies.incl 


Peponeeney: if this line has to exist but it can be empty... === SOF ILES) variable is 
list | set by ofile.incl 
Object file list The second project-specific file created by SNiFF+ for inclusion in makefiles 
(ofiles.incl) — contains the list of object files for the target of the project. Like the 


dependencies.incl, on each save of the project file the ofiles.incl is updated 
and stored in the generate directory of the project. The ofiles.incl sets the 
make variable $(OFILES), which can be used somewhere in the makefile, e.g., in 
the rule for linking the target (see makefile example above). 


OLE LLL ELEC EL OL EPC L OE LOCOCO EEE EOE ELL EL ELLE EL ELE EL EC ELEL ERLE EEA EE TEEL ETE ET EEE REEL ORPEE PAELLA ELA LL LL EEL LE EEL ELE LEE Pe 


EMACS INTEGRATION 


SNiFF+ offers two possibilities for editing source code: 
« SNiFF+'s own integrated Editor (see “Editor” on page 2193). 
« An interface to standard GNU Emacs (version 19 or newer). 


This section describes how to integrate Emacs and how to work with it in the 
SNiFF+ environment. 


The following features are available: 


Rao 


: Emacs is used for all SNiFF+ editing requests. 

# SNiFF+ recognizes and updates all browsers when a file is saved in Emacs. 
x: SNiFF+ commands can be issued directly from Emacs. 

: Emacs highlights symbols and comments like the integrated SNiFF+ Editor. 


mites 
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The following figure shows an Emacs running under X connected to SNiFF+: 


onst int. cObjyNonDeleted Nx01o000000, 
cObjDelayChanges Ox02000000, 
cObj Visited Os t4000000, 
cObj IsProto Ox08000000, 
cO0bj IsObserved OxLU000000 ; 


lass [bject Sa aS aE we Symbol and 
riend class Class; comment 
highlighting 
fe---- sutomatically aceoed Sy macro meteDer 
static class Class *zs2; 
friend IStream Soperator>> (IStream &s, 

{ return ::LoadPtr(s, op, 1 
friend class Class +_Type(Ubject*) 

{ return Object::1sa; } 
Objecticlass —dumuyt) ; 
virtual class Class *IsaAt}; 
virtual void Members (AccessMembers*) ; 


fre SNiFF+ mode 
Object (int f= edhjDefault) ; 


virtual ~Object() ; 
Virtual void FreeAlL() : 
----Emacs: Object.h (C Sniff}--11% 


Each user can have one Emacs to SNiFF+ connection active at a time. 


Integrating Emacs Integrating Emacs is fairly easy. All you need is: 

« SNiFF+ up and running 

# GNU Emacs (version 19 or later) installed at your site 
« The sniff-mode.el file (part of the SNiFF+ package) 


Telling SNiFF+ to use The Preferences dialog of SNiFF+ contains a toggle button labeled “Use Emacs”. 

Emacs Pressing the button tells SNiFF+ to use Emacs for all editing requests. If the 
button is pressed and no Emacs is actually connected to SNiFF+, a small dialog 
panel asks you whether to switch off the Emacs mode and use the own integrated 


Editor. 
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Switching Emacs to 
SNiFF+ mode 


Connecting Emacs to a 
running SNiFF+ 


Disconnecting Emacs 
from SNiFF+ 


Working w with Eiiaes 
and SNiFF+ 


Positioning Emacs from 
SNiFF+ 


The product package contains an Emacs-lisp file called sniff-mode.el that 
defines the SNiFF+ mode, how to talk to SNiFF+, and keyboard definitions for 
the available SNiFF+ commands. | 


The file is located in the directory $SNIFF_DIR/config. 
To load the sniff-mode.el file at Emacs es we suggest adding the following 
line to your .emacs file: 

(load "$SNIFF_DIR/config/sniff-mode" ) 


You can avoid the path specification by copying sniff-mode.el to the SELON. 
for site-wide Emacs-lisp files: 


cp <sniff_directory>/config/sniff-mode.el /usr/local/lib/emacs/site-lisp 


Whereby <sniff_directory> points to the root of the SNiFF+ installation. After you 
have done that, your .emacs file entry can look like this: 


(load “sniff-mode") 


Whenever Emacs is started and is switched to the sniff-mode, a connection 
between SNiFF+ and Emacs has to be created. This is done by evaluating in the 
minibuffer: 


M-x sniff-connect 


Emacs automatically recognizes when SNiFF+ is shut down and disconnects itself. 
A disconnection can be forced, though, by evaluating in the minibuffer: 


M-x sniff-disconnect 


Once a connection between SNiFF+ and Emacs is established, SNiFF+ uses Emacs 
for all requests to show or edit source code. On the other hand, Emacs can send 
queries to SNiFF+. 


With Emacs as the main editor, you have almost the same possibilities to position 
quickly to a position in the source code as with the integrated Editor. Whenever 
you double-click in the browsers of SNiFF+ on a symbol or entry that has a 
relation to the source code, Emacs loads the corresponding source file and 
positions the cursor at the location. 


When a new file is to be loaded, it is loaded into the currently active buffer (the 
buffer where the cursor is located). If the file is already loaded in a hidden 
buffer, Emacs is switched to that buffer. 


Emacs highlights symbols in the source text by using different fonts. The 
symbolic information for this is supplied by SNiFF+. Highlighting can be 
switched off (see “Configuring the Emacs integration” on page 253). 
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SNiFF+ commands 
available in Emacs 


Switching a non-SNiFF+ 
buffer to SNiFF+ mode 


integration 


Changing key bindings 


Configuring symbol 
highlighting 
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All of the SNiFF+ commands that are important when editing source code are 
also available in Emacs. To accomplish this, a few keys have been bound to 
functions that communicate with SNiFF+. The functions and the key bindings 
are defined in the sniff-mode.el file (for changing the key bindings see 
“Configuring the Emacs integration” on page 253). 


The following commands and bindings are available: 
XXX table missing from p 108 XXX 


If SNiFF+ cannot find an identifier to answer a query from Emacs, then a 
message is displayed in the echo area. 


When a file is loaded in EMACS from SNiFF+, this buffer is automatically in 
SNiFF+ mode. When a file is loaded manually (via the emacs load file command), 
the buffer can be switched to SNiFF+ mode by evaluating the following 
command: 

M-x sniff-mode 


After the command is executed, all SNiFF+ key bindings are available and 
symbols are highlighted. 


The SNiFF+ key bindings are defined in the sniff-mode.el file. You can change 
the SNiFF+ key bindings as for any other Emacs key bindings. 


EMAGCS is able to use different fonts. We use this feature to highlight symbols in 
source code. Emacs then is able to mimic the behavior of the integrated Editor. 


The symbol highlighting is on by default, but can be switched off by setting 


(setq sniff-want-fonts nil) 


in your .emacs file (or interactively with M-x set-variable). Setting this variable 
to non-nil enables symbol highlighting. 


The default font table for the highlighting is defined in the sniff-mode.e! file. 
You can change the table by setting variables in your .emacs file. An example is: 
(aset sniff-font-table 0 ‘bold-italic) 


This will tell Emacs to use bold-italic face for comments. Please see the sniff - 
mode.el file for a full description of table entries. 


PRELIMINARY TALIGENT CONFIDENTIAL: REGISTERED INFORMATION TALIGENT TOOLS FOR AIX 


254 CHAPTER 15 SUPPORT FOR OTHER FUNCTIONS 


VERSION CONTROL 


ae POLL LEE LLL EEL ELLE EL LLL ELLE LOL OOO LEE E EEOC LCL EEL EL LPL EEL 


How the Emacs 
integration works 


~ Version file and working 
file 


If symbols and comments are not highlighted although the sniff-want- fonts 
variable is set, your Emacs might use a font that doesn't supply the necessary 
faces. To make Emacs using the courier font family, which should have all the 
different faces, try the following X resource (add the line to your .Xdefaults 
file): 


emacs.font: -*-courier-medium-r-normal --*-120-75-75-*-*-*-* 


nn gD 


To work together with the SNiFF+ environment, Emacs need not be changed. An 
Emacs configuration file is supplied with the SNiFF+ distribution. This file called 
sniff-mode.el contains Emacs-lisp code and tells Emacs how to communicate 
with SNiFF+. 


Once the file is loaded, a new SNiFF+-mode is available in Emacs. Evaluating the 
function called sniff-connect builds# up an interprocess communication and 
connects Emacs to the running SNiFF+ of the same user. 


After SNiFF+ has been told to use Emacs as the main editor and after connecting, 
SNiFF+ uses Emacs to show and edit source code. Likewise, SNiFF+ provides 
commands to the Emacs user. 


SNiFF+ supports various version control systems. 
The following systems are supported: 


# RCS version 5 or newer 

# SCCS 

# SNiFF+ internal locking. This is a simple file-based locking system without 
version control features 


Each version system can be integrated into SNiFF+ with a flexible adapter 
architecture that provides a consistent user interface. 


A version file is located in the version control system repository and holds the 
complete history information of the file. | 


A working file is a checked out version and is the file that can be edited, saved, 
and checked in later. 
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Restrictions in using The following restrictions apply when using version control systems with SNiFF+: 
RCS and SCCS with 
SNiFF+ 


« Every SNiFF+ project has one version control directory, but several SNiFF+ 
projects can share one version control directory. 

# The directory names where the version files are stored can only have the 
following names: 


Version control system Directory 
RCS RCS 
SCCS SCCS 


# For RCS the filename extension of the version file must be the default , v. 

# The RCS/SCCS commands must be available in the command search path of 
the sniff process. 

« The user changing the version files must have write permission on the 
version control directories. | 

# Only strict locking is supported. 

« Access list handling of RCS is not directly supported. 

« Delete revisions is not directly supported. 

a rcsdiff,sccs diffs and rcsfreeze commands are not directly supported. 


Most of the above functionality can be made accessible in the custom menus of 
the SNiFF+ Editor (see “Custom menus” on page 221). 


Working with SNiFF+ SNiFF+ always extracts the symbolic information from the working files and not 

version control and from the version files of the version control system. The main SNiFF+ tool to 

locking control and manage the version control is the Project Editor (see “Project Editor 
with locking information shown” on page 192). The check in and check out 
operations can also be accessed from the Editor (see “File menu” on page 225). 


How RCS and SCCS are = SNiF F+ provides a flexible adapter interface and consistent user interface to RCS 
integrated and SCCS. All version control commands executed in SNiFF+ are translated to 
calls of the corresponding tools of the respective version control system. 


ent a, PPL LE PPLE OPEL EPIL LIES, 


SNIFF+ locking The integrated SNiFF+ locking is a file-based locking system without version 
control features. It is intended to be used for projects where no version control is 


needed but where locking is important. 


Information stored The SNiFF+ locking stores the general description for a file and a log of changes 
to that file. The locking information is stored in a file called sourcefile.1ck in the 
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APPENDIX B 


GNU REGULAR EXPRESSIONS 


GNU regular expressions are a very powerful means to specify patterns for filters . 
and search strings in the various tools of SNiFF+. The syntax conforms to the - oe ; 
regular expression syntax used in the EMACS editor. _ 


// Extended regular expression matching and search. 
// Copyright (C) 1985 Richard M. Stallman 


The GNU regular expression facilities are like those of most Unix editors, but 
more powerful: 


* specifies a repetition of the preceding expression 0 or more times. 
+ is like *, but specifies repetition of the preceding expression | or more times. 
? is like *, but matches at most one repetition of the preceding expression. 


\| specifies an alternative. Two regular expressions A and B with \l in between 
form an expression that matches anything that either A or B will match. Thus, 
“foo\lbar” matches either “foo” or “bar”, but no other string. 


\| applies to the largest possible surrounding expressions. Only a surrounding \( 
... \) grouping can limit the grouping power of \. 


Full backtracking capability exists when multiple N's are used. 
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-- \digit -- 


SE\Ye: 
oaN! se 


--\b -- 


NBs 
ee 
a 


-- \w -- 


APPENDIX BGNU REGULAR EXPRESSIONS 


\(... \) are a grouping construct that serves three purposes: 
# To enclose a set of \| alternatives for other operations. 
Thus, “\(foo\lbar\)x” matches either “foox” or “barx”. 
# To enclose a complicated expression for * to operate on. 
Thus, “ba\(na\)*” matches “bananana”, etc., with any number of na's (zero or 
more). 
« To mark a matched substring for future reference. 
Application 3 is not a consequence of the idea of a parenthetical grouping; it is a 
separate feature that happens to be assigned as a second meaning of the same \( 
... \) construct because there is no conflict in practice between the two meanings. 
The following is an explanation of this feature. 


After the end of a \( ... \) construct, the matcher remembers the beginning and 
end of the text matched by that construct. Then, later on in the regular 
expression, you can use \ followed by a digit to mean, “match the same text 
matched this time by the \( ... \) construct." The first nine \( ... \) constructs that 
appear in a regular expression are assigned numbers 1 through 9 in order of 
their beginnings. \l through \9 can be used to refer to the text matched by the 
corresponding \( ... \) construct. 


For example, “\(.*\)\1” matches any string that is composed of two identical 
halves. The “\(.*\)” matches the first half, which can be anything, but the \1 that 
follows must match the exact text. 

Matches the empty string, but only if it is at the beginning of the buffer. 
Matches the empty string, but only if it is at the end of the buffer. 


Matches the empty string, but only if it is at the beginning or end of a word. 
Thus, “\bfoo\b” matches any occurrence of “foo” as a separate word. 


‘\bball\(s\\)\b” matches “ball” or “balls” as a separate word. 

Matches the empty string, provided it is NOT at the beginning or end of a word. 
Matches the empty string, provided it is at the beginning of a word. 

Matches the empty string, provided it is at the end of a word. 


Matches any word-constituent character. The editor syntax table determines 
which characters these are. 
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-- \W -- Matches any character that is not a word-constituent. 
-- \s<code> -- Matches any character whose syntax is <code>. <code> is a letter that represents a 
syntax code: thus, “w” for word constituent, “-” for whitespace, “(” for open- 


parenthesis, etc. Thus, “\s(” matches any character with open-parenthesis syntax. 


-- \S<code> -- Matches any character whose syntax is not <code>. 
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APPENDIX C 


ETRC FILE ENTRIES 


The ETRC file stores all preference settings. Site-specific preferences are stored 
in the ETRC file located in the SNiFF+ installation directory. User-specific 
preferences are stored in the ETRC file located in the user's home directory. _ 


Some entries of the user-specific ETRC file can be edited with the Preferences 


- entries must be edited in the corresponding files directly. 


DESCRIPTION OF ENTRIES 


PRELIMINARY 


ETRC entries for all SNiFF+ applications (sniff and sniffgdb) 


Resource name Default value Description 


* WindowSystem.DoubleBuffer(Bool): YES Double buffering gives flicker- 
free screen updates 

* WindowSystem.ForceMonochrome(Bool): NO 
monochrome output 


* WindowSystem.MaxDepth(Num): 32 Maximum bits/pixel on color 
systems 


* WindowSystem.HighlightColor(RGBColor): 20 255 255 0 0 Color for selections and 


#yellow highlights. Format: Don’t-change 
Don't-change Red Green Blue 
Alpha. Alpha should always be 0. 
Range for RGB values: 0 - 255. 


* WindowSystem.WindowBackgroundColor(RGB 2 0 190 190 190 0 Background color of windows. 


Color): #grey For format see 


WindowSystem.HighlightColor. 
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Display only1 bit per pixel; force 


261 


262 


APPENDIX CETRC FILE ENTRIES 
DESCRIPTION OF ENTRIES 


Resource name 


Default value 


Description 


r): 


* WindowSystem.DisableColor(RGBColor) 


* IAC. Debug(Bool) 


* oysFont: 


* ApplFont: 


* FixedFont: 


* LineSpacing: 
* TextView.CaretColor(RGBColor): 


* shellText.UseStyles(Bool): 


* CodeText. UseStyles(Boo!) 


Sen re EEE ELLE OLE LE OEE LEE EE LOLOL BOL EE OEE LOL EL ROLLIE LEE ELLE LOLOL EEE CELL LEED ELE LLCO LED LEE DEE: 
. 
. 


* CodeText.AllowGraphics(Bool) 


* CodeText.TabPos(Num) 


* WindowSystem.ViewBackgroundColor(RGBColo 


20 255 255 255 0 
#white 


#dark grey 


Chicago-Medium-12 


‘Helvetica-Medium-12 


Courier-Medium-12 


60255000 


#red 


YES 


20 144 144 144.0 


FALSE =i (atit*s 


YS 


Background color of all views 
(also Editor text view). For 
contrast reasons you might also 
want to change Sniff.Code.Color 
etc. For format, see 
WindowSystem.HighlightColor 


Color of disabled items. For | 
format, see 
WindowSystem.HighlightColor 


Interapplication communicator 
prints control messages to stderr 


System font: Family-Face-Size 
(possible values are listed in the 
ETRC file) 


Application font: Family-Face- 
Size 


Fixed font: Family-Face-Size for 
fixed text views (Editor, Shell, 
Debugger) 


General line spacing for all fonts 


and all tools 


Color of caret (Cursor) in 

textview. For format, see 
WindowSystem.HighlightColor. 
Allow different styles ina Shell 


Allow different styles in source 
text view 


Allow graphical objects 


 Tabulator width for non-SNiFF+ 


files 


* CodeText.WordWrap(Boo)l): 


* ScrollBar Thickness: | 
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16 


Wrap words around lines if text 
gets too long 


Width of scrollbars —_ 
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Resource name 


Doc.FieldName.Font 


#Doc.FieldName.Color 


#Doc.Emphasis 


Doc.Obsoleteltem.Color 


* SHELL: 


Resource name 


Sniff.StoreState: 


Sniff. TabSize: 


Sniff. MakeCommand: 


Sniff.lncludePostfixes,  o9«§«si(<itéiCS . 
Sniff. SourcePostfixes: | 
Sniff.Emacs: | 
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Default value 


Times-Bold 


20190 190 190 0 


/bin/esh | 


Default value 


YES 


10:10:250:200 


| NO . | Use Emacs as editor 
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DESCRIPTION OF ENTRIES 


Description 


Create a backup copy 
(filename) on a file save 


Font for field names 
Color of field names 


Font for normal text 


Indent for indented text 


Shell used for the Shell 


Description 


Store the window positions and 


sizes between sessions 


Workspace Manager window 


Default Tabulator width (can be 
overridden for each project) 


Command called on makes 


files (Format: ':'-separated list) 


Recognized suffixes of 


implementation files (Format: ':'- 
separated list) 


Location and size of the 
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DESCRIPTION OF ENTRIES 


Resource name _— Default value Description 


PPPPPE PPE PE PeeeeTTeeLereeeeereeeereeeeere reer eee eeeee eee reer ereee reer eee e eee cree eee ree rer eee rere rer er ee erect reer reer eer err er errr er eer eee ere reer eer ere errr rere rere rer eer eee errr reer ere retiree rier ese ere reer rere rrr eter eerie er rer ree rer ee etree te etree reer er errr eerste errr rrr ee rre reer etree errr rere rere ree ee reir irs 


Sniff.ManualPath: : Search paths for documentation 
files (Format: ':'-separated list) 
File defining additional filters for 
the Retriever 


SniffFilterFile: 


Sniff.RetrieverCache: | TRUE Cache source files after the first 


Sniff.HistorySize: 10 Maximum number of recallable 
history entries in the History 
menus 


Sniff. femplateDir: Directory where templates for 
newly created files are stored 

Sniff.PopupErrorLog: FALSE The Error Log window is 
automatically opened when a 
message is written to 


Courier-Medium-12 Editor code font: Family-Face- | 
Size 


Sniff.Code.Color: 200000 Color for normal code. For format 


#black See 
WindowSystem.HighlightColor 


sniff.Comment.Font: Courier-Medium-12 | Comment font: Family-Face-Size 


Sniff.Comment.Color: | 20 92 99 99 0 Color for comments. For format | 


#dark grey see 
WindowsSystem.HighlightColor 


Sniff.Macro.Font: Courier-Bold-12 Macro font: Family-Face-Size 


Sniff.Macro.Color: 20 9292 92 0 Color for macros. For format see 
#dark grey WindowSystem.HighlightColor 


Sniff.Class.Font: Courier-Bold-12 Class font: Family-Face-Size 


Sniff.Class.Color: 20 929292 0 Color for classes. For format see 
#dark grey WindowSystem.HighlightColor 
Sniff. InstVar.Font: Courier-BoldOblique- _—_—‘ Instance variable font: Family- 
12 Face-Size 
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Resource name 


Sniff Function. Font: 


SniffFunction.Color; = 


Sniff. Friend.Font: | 


Sniff. TypeDef.Color: 


Sniff. Variable.Font: — 


Sniff.Const.Color: 
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Default value 


20 929292 0 
#dark grey 


20 929292 0 
#dark grey 


20 929292 0 
#dark grey 


APPENDIX CETRC FILE ENTRIES 
DESCRIPTION OF ENTRIES 


Description 


Color for instance vars. For 
format see 
WindowSystem.HighlightColor 


Method definition font: Family- 
Face-Size 


Color for methods defs. For 
format see 
WindowSystem.HighlightColor 


Method implementation font: 
Family-Face-Size 


Color for method impls. For 
format see 
Windowsystem.HighlightColor 


Courier-Bold- 42 | 


#dark grey 


209292920 —_ Color for functions. For format 


see 
WindowSystem.HighlightColor 


Friend font: ee Mena 


Courier-Bold-12 | 


2 0 92 99 92 0 
#dark grey 


20 9292 92 0 
#dark grey 


Courier-Bold- 42 


#dark grey 


20 929292 0 
#dark grey 
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Color for friends. For format see 
WindowSystem.HighlightColor 


Courier-Bold- 12 Type definition font Family-Face- 


Size 


Color for typedefs. For format see 
Windowsystem.HighlightColor 


209292920 Color for variables. For format — 


see 
WindowSystem.HighlightColor 


Color for constants. For format 
see 


WindowSystem.HighlightColor 


Function font: Family-Face-Size 


Variable font: Family-Face-Size 
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DESCRIPTION OF ENTRIES | 


Resource name Default value Description 


Sniff.Enum.Font: Courier-Bold-12 ‘Enumeration font: Family-Face- 
size 


Sniff.Enum.Color: = a 20 92 92 92 0 - Color for enumerations. For | 


#dark grey format see 
WindowSystem.HighlightColor 


Sniff.Enumltem.Font: _ Courier-Bold-12 Enumeration item font Family- 
Face-Size 


Sniff.Enumltem.Color: | | 20 9292 92 0 _ Color for enumeration items. For 


WindowSystem.HighlightColor 


ETRC entries for sniffgdb 


sniffgdb.DebuggerExec: gdb Name of the debugger executable 
(must conform with the 
DebuggerAdaptor) 


Gdb4Adaptor sniffgdb adaptor for the 
debugger backend (must 
conform with the DebuggerExec) 


sniffgdb.DebuggerAdaptor: 


sniffgdb.DebuggerPrompt: (gdb) Prompt shown in the Debugger 


sniffgdb.AddETSupport(Bool) NO Add support for the ET++ 
programming environment. 
Setting it to YES will add a new 
menu Called Inspect that allows 
invocation of the ETPE from 
within sniffgdb. 
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ION 


PRELIMINARY 


hy 


INDEX 


A 


about dialog, 175 
abstract classes 


in Hierarchy Browser, 208 | 


in Symbol Browser, 204 
AIX, 5 
analysis tools, 59 
applications 

building, 9, 30 

running, 16 
architecture, 169 
assignment filter, 212 


backup file, 263 
binaries, 7 
breakpoints, setting, 222 
build | 
clean, 17 
definition, 7 
environment variables, 12 
examples, 13 
generating, 28 
global targets and rules, 11 
log listing, 15 
mistake, one target, 10 
phases of, 8 
process, 8 
terminology, 7 
build tools, 23-35 
building projects, 7 
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C++ templates, 205 
C/C++ syntax, 213 
call filter, 212 
cd, shortcuts, 95 
cdpath (environment variable), 95 
changing directories, shortcuts, 95 
Check in 
in Editor, 215, 225 
in Project Editor, 194 
Check out 
in Editor, 215, 225 
in Project Editor, 194 
Class Browser, 206 
Class menu, 180 
Class pop-up, 214, 225 
cleaning up after a test, 110 
client files, 7 
collecting timing information, 123 
colors, setting, 264, 265, 266 
combining 
multiple TTest objects into single test, 114 
operations into a single test class, 112 
tests, 112 
commandline, 135 
commands, custom, 240 
comment, 216 
comparison Filter, 212 
compilation errors, jumping to, 228 
compiler options, 13 | 
copy, 182, 216, 226 
CopylInfo, identifying what test does, 115 
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2'70 INDEX 


copying files, 34 
cp 
— See SmartCopy 

CreateMake 

definition, 24 

a) ramsey ae) 
creating a test 

dependencies on other tests, 114 

requirements, 108 
-cshre 

directory shortcuts, 95 
Custom menu, 240 
Cut, 182, 216, 226 


D 


debug target, 219, 228 
debugger 

See xcdb 

commands in Editor, 222 

custom menu, 240 
declaration, switching to, 217 
default text, 226 
define parser configuration, 237 
dependencies for make, 249 
dependencies, creating tests with, 114 
designing a test, 107 
Directories menu, 173 
directory, changing to, shortcuts, 9 5 
Directory dialog, 174 
Directory pop-up, 173, 175 
Documentation Browser, 224 
dragging text, in the Editor, 223 


E 


.e 
See export file 

Edit menu, 216, 226 

editing shortcuts, 223 

editing state, 214, 224 

editor, 213 
Class pop-up, 214, 225 
custom menu, 240 
dragging text, 223 
editing state icon, 214, 224 
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Emacs, 213 

fast copying, 223 

find/changing, 217 

list of symbols, 214, 225 

matching brackets, 223 

positioning, 217 

text selection, 223 
EditorCustomMenu, 240 
Emacs, 250 

configuring integration, 253 

integrating, 251 

working with, 252 
emphasized text, 226 
environment variables 


build, 12 
setting, 12-13 
error 


“Undefined symbol”, 25 
Error log window, 177 
ErrorFormats file, 241 
ETRC file entries, 261 
examining test results, 123 
exception 

Cleanup function, 110 

handling, 123 

stopping a test, 122 
executables 

building, 30 | 

definition, 7 
executing applications, 16 
export file 

definition, 7 

generating, 27 
extendable filters, 212 


F 


fast copying, 223 
file copying, 34 
File dialog, 172 
File level symbol persistency, 243, 250 
File list, 188 
File menu 
of the Editor, 214, 225 
of the Project Editor, 188 
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files 
custom menu, 240 
directories & paths, 232 
ETRG, 239, 261 © 
makfile support files, 249 
project file, 229, 244 
Retriever filters, 240 
suffixes for, 233 
templates, 240 
used by SNiFF+, 239 

Files menu, 173 

Filter menu, 181, 212 


filters 
extendable set of, 212, 240 
predefined 
Assignment, 212 
Call, 212 
Comparison, 212 
New, 212 


semantic, 210 

syntax for, 257 
Find Error, 228 
Find/Change Dialog, 171 
FindSymbols, 25 
fonts | 

setting, 262 

setting in Emacs, 253 


G 


generate directory, 200 
generating 
builds, 28 
executables, 30 
export files, 27 
libraries, 30 
genproj, 246 
grep, Retriever, 210 
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wh 

See header file 
handling exceptions, 123 
header file, 7 
heap corruption, 64 
heap tools, 59 
Hide overridden, 207 
Hiding classes in the Hierarchy Browser, 209 
Hierarchy menu, 209 
Hierarchy Browser, 208 
history 

menu, 181 

setting size, 264 
History text, 196 


Icon menu, 177 
identifying what a test does, 115 
ignore string 

parser configuration file, 237 
Implementation 

switching to, 217 
Info menu, 179 
Information extractor, see sniffserver, parser 
Inheritance relationship, 208 
Inheritance Tree, 207 
input 

parsing for test, 119 

test, 119 
InterViews, 245 
IpCPurge, 27 

See also mop 


K 


key bindings in Emacs, 253 
keyboard shortcuts, 183 
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Layout handle, 170 
libraries 
building from smaller libraries, 10 
generating, 30 
linking to export files, 27 
library projects, overlaying files, 234 
License dialog, 1'76 
line spacing, 262 
list of symbols, 204 
locking 
in Project editor, 192 
Locking menu, 194 
Project Editor, 192 
look, Motif, 233 


macro parsing problems, 236 
make 
command, 234 
dependencies.incl, 249 
menu, 189, 219 
ofiles.incl, 250 
receiving options from Makeit, 11 
support for makefiles, 249 
See also Makeit, 10 


.Make, missing builds new makefile, 11 


MakeC++SharedLib, 30 
MakeExportList, 27 
makefile, 9-10 
description 
check in to RCS, 9g 
naming convention, 9 


standard makefile, translating to, 9 


syntax, 9 
target types, 9 
standard makefile, creating, 9 
syntax, Q 
targets, 9 
update, 189, 218 
when to build, 11 
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Makeit 
definition, 28 
log listing, 15 
makefiles, when to build, 11 
passing options to make, 11 
MakeSharedApp, 30 
MakeShredLib, 30 
MakeSOL, 31 
matching brackets, 223 
Menu commands 
custom, 240 
shortcuts, 183 
modified icon, 214, 224 
mop, 31 | 
Motif look, 233 
multiple users, see locking » 


nest, 216 
new filter, 212 


0 


object file list for make, 250 
options 
compiler, 13 
overriding with variables, 13 
options, RunTest, 121 
overridden, hide, 207 
overriding, inherited MCollectible members of TTest, 110 


P 


parser 
configuration file, 239 
dealing with preprocessor macros, 236 
see also sniffserver 

parsing text inputs to test, 119 

paste, 182, 216, 226 

performing a test, 118 

persistency 
file level, 243, 250 
of SNiFF+ symbols, 243 
project level, 243 
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.PinkMake, newer than *.Make, 11 
polymorphic testing, 118 
predefined filters, 212 
preferences, 231 
colors, 264, 265, 266 
ETRG, 261 
fonts, 262 
history size, 264 
Preferences dialog, 232 
Preprocessor macros, 236 
Print dialog, 175 
programs, building, 30 
Progress window, 176 
project 
building, 10 
building subprojects, 10 
with many subprojects, 246 
with separate implementation and declaration 
directories, 245 
Project Attributes dialog 
for frozen subprojects, 203 
for subprojects, 2093 
Project Editor, 187 
Project file, 244 
project hierarchy 
See project 
project level symbol persistency, 243 
Project menu, 186, 189 
Project tree, 188 
protocol tests, 105 
providing input for test, 119 
purify, understanding messages from, 241 


R 


RCS, 254, 192 

Redo, 182, 216, 226 

regular expressions syntax, 257 
resources, purging, 27 

results, examining test, 123 
Retriever, 210, 240 

reusable status, 1'70 

Run, 222 

RunDocument, 32 

running applications, 16 
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Run Test 
options, 121 
overview, 117 
run multiple tests, 112 


S 


~SCCS, 254, 192 


ScreamPlus, 31 
script, run multiple tests, 112 
search string, 210 
selecting text, 223 
semantic filtering, 210 
Setenv, 12 
setup, test framework, 110 
shared libraries 
building, 9 
definition, 7 
generating, 30 
linking to export files, 27 
SharedLibCache, 33 
shell tool, 227 
shortcuts 
editing, 223 
for menu commands, 183 
single stepping, 222 
site specific preferences, 231 
slcache 
See SharedLibCache 
Slibclean, 33 
SmartCopy, 34 
SNiFF+ locking, 255 
sniff-connect, 252 
sniff-disconnect, 252 
sniffserver, 235 
running on a remote host, 236 
see also parser, 235 
source files 
specifying in a project, 197 
suffixes for, 232 
StartPink, 34 
status line, 170 
stopping, test, 122 
StopPink, 35 
streaming operators, test framework, 110 
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subproject, 190 | 
subproject, building, 10 
suffixes, for sources files, 233 
super Class, quick positioning to, 217 
Symbol Browser, 204 
Symbol list 

in the Editor, 214, 225 

in the Symbol Browser, 204 
Symbol table, 169 

persistency of, 243 

Update, 218 
syntax, for regular expressions, 257 


T 


target 
debug, 219, 228 
make, 218, 228 
name, 200 
teamwork, support for, 234 
template files, 240 
templates, C++, 205 
test 
creating, 108 
designing, 107 
examining results, 123 
identifying what test does, 115 
input, 119 
interface inherited from base class, 118 
parsing input, 119 
performing, 118 
polymorphic, 118 
stopping, 122 
test framework 
class hierarchy, 104 
cleanup, 110 
collecting timing information, 123 
combining multiple TTest objects, 114 
combining operations in a single test, 112 
combining tests, 112 
example, 106 
header files, 108 
identifying test, 115 
overriding MCollectible members, 110 
overview, 103, 104 
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performing a test, 118 

run test more than once, 110 

script, 112 

setup function, 110 

test function, 109 

tests with dependencies, 114 
test function, writing, 109 
this, 222 
timing information, collecting, 123 
tips and techniques, 95 
TLocalHeapAnalyzer, 62 
TLocalHeapMonitor, 61 
TMCollectibleTest, 105 
TTest 

combining, 114 

description, 104 

hierarchy, 104 
TTestCollection, 105 
TTestMultiplexer 

definition, 105 

usage, 112 


TTextArgumentDictionary, test framework, 106 


TTieredText, test framework, 106 
TTieredTextBuffer 

test framework, 106 

writing text to console, 111 
TTimingTest, 105 
Tuning, 243 
Type Pop-up 

Class Browser, 207 

Symbol Browser, 205 


U 


Undo, 182, 216, 226, 263 
Universal .Make, ll 

UNIX, shell interface, 227 
update Makefiles, 189, 218 


V 


version control, 192, 254 
version file, 254 
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W 


window status 
files, 242 
preferences setting, 233 
working file, 193, 254 
Workspace Manager, 185 
writing a test function, 109 
writing a test to run more than once, 110 
writing text to the console, 111 
WYSIWYG, 213 


X 


xcdb (debugger), 96 
xdb, 96 
xLC, wrapper for, 30 
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